@push.rocks/smartproxy 26.2.4 → 27.0.0

package/readme.md

@@ -1,6 +1,6 @@
 # @push.rocks/smartproxy 🚀
 
-**A high-performance, Rust-powered proxy toolkit for Node.js** — unified route-based configuration for SSL/TLS termination, HTTP/HTTPS reverse proxying, WebSocket support, UDP/QUIC/HTTP3, load balancing, custom protocol handlers, and kernel-level NFTables forwarding.
+**A high-performance, Rust-powered proxy toolkit for Node.js** — unified route-based configuration for SSL/TLS termination, HTTP/HTTPS reverse proxying, WebSocket support, UDP/QUIC/HTTP3, load balancing, custom protocol handlers, and kernel-level NFTables forwarding via [`@push.rocks/smartnftables`](https://code.foss.global/push.rocks/smartnftables).
 
 ## 📦 Installation
 
@@ -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';
-
-let apiRoute = createApiGatewayRoute(
-  'api.example.com',
-  '/api',
-  { host: 'api-backend', port: 8080 },
-  {
-    useTls: true,
-    certificate: 'auto',
-    addCorsHeaders: true
-  }
-);
+import { SmartProxy } from '@push.rocks/smartproxy';
 
-// 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';
-
-// Use pre-built handlers
-const echoRoute = createSocketHandlerRoute(
-  'echo.example.com',
-  7777,
-  SocketHandlers.echo
-);
-
-// 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`);
-      }
-    });
-  }
-);
+import { SmartProxy, SocketHandlers } from '@push.rocks/smartproxy';
 
-const proxy = new SmartProxy({ routes: [echoRoute, customRoute] });
+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');
+
+          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`);
+            }
+          });
+        }
+      }
+    }
+  ]
+});
 ```
 
 **Pre-built Socket Handlers:**
@@ -384,23 +418,26 @@ const dualStackRoute: IRouteConfig = {
 
 ### ⚡ High-Performance NFTables Forwarding
 
-For ultra-low latency on Linux, use kernel-level forwarding (requires root):
+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
 
@@ -694,22 +726,26 @@ SmartProxy uses a hybrid **Rust + TypeScript** architecture:
 │  │ Listener│ │ Reverse  │ │ Matcher │ │ Cert Mgr │  │
 │  │         │ │  Proxy   │ │         │ │          │  │
 │  └─────────┘ └─────────┘ └─────────┘ └──────────┘  │
-│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────┐  │
-│  │   UDP   │ │ Security│ │ Metrics  │ │ NFTables │  │
-│  │  QUIC   │ │ Enforce │ │ Collect  │ │  Mgr     │  │
-│  │  HTTP/3 │ │         │ │          │ │          │  │
-│  └─────────┘ └─────────┘ └─────────┘ └──────────┘  │
+│  ┌─────────┐ ┌─────────┐ ┌─────────┐               │
+│  │   UDP   │ │ Security│ │ Metrics  │               │
+│  │  QUIC   │ │ Enforce │ │ Collect  │               │
+│  │  HTTP/3 │ │         │ │          │               │
+│  └─────────┘ └─────────┘ └─────────┘               │
 └──────────────────┬──────────────────────────────────┘
                    │  Unix Socket Relay
 ┌──────────────────▼──────────────────────────────────┐
 │   TypeScript Socket & Datagram Handler Servers       │
 │  (for JS socket handlers, datagram handlers,         │
 │   and dynamic routes)                                │
+├─────────────────────────────────────────────────────┤
+│   @push.rocks/smartnftables (kernel-level NFTables)  │
+│  (DNAT/SNAT, firewall, rate limiting via nft CLI)    │
 └─────────────────────────────────────────────────────┘
 ```
 
 - **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)
 
@@ -854,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
@@ -906,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
 
@@ -938,8 +940,8 @@ class SmartProxy extends EventEmitter {
   getCertificateStatus(routeName: string): Promise<any>;
   getEligibleDomainsForCertificates(): string[];
 
-  // NFTables
-  getNfTablesStatus(): Promise<Record<string, any>>;
+  // NFTables (managed by @push.rocks/smartnftables)
+  getNfTablesStatus(): INftStatus | null;
 
   // Events
   on(event: 'error', handler: (err: Error) => void): this;
@@ -991,11 +993,11 @@ interface ISmartProxyOptions {
   sendProxyProtocol?: boolean;              // Send PROXY protocol to targets
 
   // Timeouts
-  connectionTimeout?: number;               // Backend connection timeout (default: 30s)
-  initialDataTimeout?: number;              // Initial data/SNI timeout (default: 120s)
-  socketTimeout?: number;                   // Socket inactivity timeout (default: 1h)
-  maxConnectionLifetime?: number;           // Max connection lifetime (default: 24h)
-  inactivityTimeout?: number;               // Inactivity timeout (default: 4h)
+  connectionTimeout?: number;               // Backend connection timeout (default: 60s)
+  initialDataTimeout?: number;              // Initial data/SNI timeout (default: 60s)
+  socketTimeout?: number;                   // Socket inactivity timeout (default: 60s)
+  maxConnectionLifetime?: number;           // Max connection lifetime (default: 1h)
+  inactivityTimeout?: number;               // Inactivity timeout (default: 75s)
   gracefulShutdownTimeout?: number;         // Shutdown grace period (default: 30s)
 
   // Connection limits
@@ -1004,8 +1006,8 @@ interface ISmartProxyOptions {
 
   // Keep-alive
   keepAliveTreatment?: 'standard' | 'extended' | 'immortal';
-  keepAliveInactivityMultiplier?: number;   // (default: 6)
-  extendedKeepAliveLifetime?: number;       // (default: 7 days)
+  keepAliveInactivityMultiplier?: number;   // (default: 4)
+  extendedKeepAliveLifetime?: number;       // (default: 1h)
 
   // Metrics
   metrics?: {
@@ -1137,7 +1139,7 @@ SmartProxy searches for the Rust binary in this order:
 
 ## License and Legal Information
 
-This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](./license) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartproxy',
-  version: '26.2.4',
+  version: '27.0.0',
   description: 'A powerful proxy package with unified route-based configuration for high traffic management. Features include SSL/TLS support, flexible routing patterns, WebSocket handling, advanced security options, and automatic ACME certificate management.'
 }

package/ts/plugins.ts

@@ -19,12 +19,14 @@ export { tsclass };
 import * as smartcrypto from '@push.rocks/smartcrypto';
 import * as smartlog from '@push.rocks/smartlog';
 import * as smartlogDestinationLocal from '@push.rocks/smartlog/destination-local';
+import * as smartnftables from '@push.rocks/smartnftables';
 import * as smartrust from '@push.rocks/smartrust';
 
 export {
   smartcrypto,
   smartlog,
   smartlogDestinationLocal,
+  smartnftables,
   smartrust,
 };
 

package/ts/proxies/smart-proxy/rust-proxy-bridge.ts

@@ -15,7 +15,6 @@ type TSmartProxyCommands = {
   renewCertificate:      { params: { routeName: string };        result: void };
   getCertificateStatus:  { params: { routeName: string };        result: any };
   getListeningPorts:     { params: Record<string, never>;        result: { ports: number[] } };
-  getNftablesStatus:     { params: Record<string, never>;        result: any };
   setSocketHandlerRelay: { params: { socketPath: string };       result: void };
   addListeningPort:      { params: { port: number };             result: void };
   removeListeningPort:   { params: { port: number };             result: void };
@@ -159,10 +158,6 @@ export class RustProxyBridge extends plugins.EventEmitter {
     return result?.ports ?? [];
   }
 
-  public async getNftablesStatus(): Promise<any> {
-    return this.bridge.sendCommand('getNftablesStatus', {} as Record<string, never>);
-  }
-
   public async setSocketHandlerRelay(socketPath: string): Promise<void> {
     await this.bridge.sendCommand('setSocketHandlerRelay', { socketPath });
   }

package/ts/proxies/smart-proxy/smart-proxy.ts

@@ -23,8 +23,8 @@ import type { IMetrics } from './models/metrics-types.js';
 /**
  * SmartProxy - Rust-backed proxy engine with TypeScript configuration API.
  *
- * All networking (TCP, TLS, HTTP reverse proxy, connection management, security,
- * NFTables) is handled by the Rust binary. TypeScript is only:
+ * All networking (TCP, TLS, HTTP reverse proxy, connection management, security)
+ * is handled by the Rust binary. TypeScript is only:
  * - The npm module interface (types, route helpers)
  * - The thin IPC wrapper (this class)
  * - Socket-handler callback relay (for JS-defined handlers)
@@ -39,6 +39,7 @@ export class SmartProxy extends plugins.EventEmitter {
   private socketHandlerServer: SocketHandlerServer | null = null;
   private datagramHandlerServer: DatagramHandlerServer | null = null;
   private metricsAdapter: RustMetricsAdapter;
+  private nftablesManager: InstanceType<typeof plugins.smartnftables.SmartNftables> | null = null;
   private routeUpdateLock: Mutex;
   private stopping = false;
   private certProvisionPromise: Promise<void> | null = null;
@@ -211,6 +212,9 @@ export class SmartProxy extends plugins.EventEmitter {
       }
     }
 
+    // Apply NFTables rules for routes using nftables forwarding engine
+    await this.applyNftablesRules(this.settings.routes);
+
     // Start metrics polling BEFORE cert provisioning — the Rust engine is already
     // running and accepting connections, so metrics should be available immediately.
     // Cert provisioning can hang indefinitely (e.g. DNS-01 ACME timeouts) and must
@@ -238,6 +242,12 @@ export class SmartProxy extends plugins.EventEmitter {
       this.certProvisionPromise = null;
     }
 
+    // Clean up NFTables rules
+    if (this.nftablesManager) {
+      await this.nftablesManager.cleanup();
+      this.nftablesManager = null;
+    }
+
     // Stop metrics polling
     this.metricsAdapter.stopPolling();
 
@@ -319,6 +329,13 @@ export class SmartProxy extends plugins.EventEmitter {
         this.datagramHandlerServer = null;
       }
 
+      // Update NFTables rules
+      if (this.nftablesManager) {
+        await this.nftablesManager.cleanup();
+        this.nftablesManager = null;
+      }
+      await this.applyNftablesRules(newRoutes);
+
       // Update stored routes
       this.settings.routes = newRoutes;
 
@@ -411,14 +428,59 @@ export class SmartProxy extends plugins.EventEmitter {
   }
 
   /**
-   * Get NFTables status (async - calls Rust).
+   * Get NFTables status.
    */
-  public async getNfTablesStatus(): Promise<Record<string, any>> {
-    return this.bridge.getNftablesStatus();
+  public getNfTablesStatus(): plugins.smartnftables.INftStatus | null {
+    return this.nftablesManager?.status() ?? null;
   }
 
   // --- Private helpers ---
 
+  /**
+   * Apply NFTables rules for routes using the nftables forwarding engine.
+   */
+  private async applyNftablesRules(routes: IRouteConfig[]): Promise<void> {
+    const nftRoutes = routes.filter(r => r.action.forwardingEngine === 'nftables');
+    if (nftRoutes.length === 0) return;
+
+    const tableName = nftRoutes.find(r => r.action.nftables?.tableName)?.action.nftables?.tableName ?? 'smartproxy';
+    const nft = new plugins.smartnftables.SmartNftables({ tableName });
+    await nft.initialize();
+
+    for (const route of nftRoutes) {
+      const routeId = route.name || 'unnamed';
+      const targets = route.action.targets;
+      if (!targets) continue;
+
+      const nftOpts = route.action.nftables;
+      const protocol: plugins.smartnftables.TNftProtocol = (nftOpts?.protocol as any) ?? 'tcp';
+      const preserveSourceIP = nftOpts?.preserveSourceIP ?? false;
+
+      const ports = Array.isArray(route.match.ports)
+        ? route.match.ports.flatMap(p => typeof p === 'number' ? [p] : [])
+        : typeof route.match.ports === 'number' ? [route.match.ports] : [];
+
+      for (const target of targets) {
+        const targetHost = Array.isArray(target.host) ? target.host[0] : target.host;
+        if (typeof targetHost !== 'string') continue;
+
+        for (const sourcePort of ports) {
+          const targetPort = typeof target.port === 'number' ? target.port : sourcePort;
+          await nft.nat.addPortForwarding(`${routeId}-${sourcePort}-${targetPort}`, {
+            sourcePort,
+            targetHost,
+            targetPort,
+            protocol,
+            preserveSourceIP,
+          });
+        }
+      }
+    }
+
+    this.nftablesManager = nft;
+    logger.log('info', `Applied NFTables rules for ${nftRoutes.length} route(s)`, { component: 'smart-proxy' });
+  }
+
   /**
    * Build the Rust configuration object from TS settings.
    */