@push.rocks/smartproxy 18.0.2 → 18.2.0

package/readme.md

@@ -9,6 +9,7 @@ A unified high-performance proxy toolkit for Node.js, with **SmartProxy** as the
 - **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
+- **NFTables Integration**: High-performance kernel-level packet forwarding with Linux NFTables
 
 ## Project Architecture Overview
 
@@ -71,6 +72,8 @@ SmartProxy has been restructured using a modern, modular architecture with a uni
   Helper functions for common redirect and security configurations
 - **createLoadBalancerRoute**, **createHttpsServer**
   Helper functions for complex configurations
+- **createNfTablesRoute**, **createNfTablesTerminateRoute**
+  Helper functions for NFTables-based high-performance kernel-level routing
 
 ### Specialized Components
 
@@ -108,7 +111,7 @@ npm install @push.rocks/smartproxy
 
 ## Quick Start with SmartProxy
 
-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.
+SmartProxy v18.0.0 continues the evolution of the unified route-based configuration system making your proxy setup more flexible and intuitive with improved helper functions and NFTables integration for high-performance kernel-level routing.
 
 ```typescript
 import {
@@ -122,7 +125,9 @@ import {
   createStaticFileRoute,
   createApiRoute,
   createWebSocketRoute,
-  createSecurityConfig
+  createSecurityConfig,
+  createNfTablesRoute,
+  createNfTablesTerminateRoute
 } from '@push.rocks/smartproxy';
 
 // Create a new SmartProxy instance with route-based configuration
@@ -185,7 +190,22 @@ const proxy = new SmartProxy({
           maxConnections: 1000
         })
       }
-    )
+    ),
+
+    // 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'
+    })
   ],
 
   // Global settings that apply to all routes
@@ -319,6 +339,12 @@ interface IRouteAction {
 
   // Advanced options
   advanced?: IRouteAdvanced;
+
+  // Forwarding engine selection
+  forwardingEngine?: 'node' | 'nftables';
+
+  // NFTables-specific options
+  nftables?: INfTablesOptions;
 }
 ```
 
@@ -349,6 +375,25 @@ interface IRouteTls {
 - **terminate:** Terminate TLS and forward as HTTP
 - **terminate-and-reencrypt:** Terminate TLS and create a new TLS connection to the backend
 
+**Forwarding Engine:**
+When `forwardingEngine` is specified, it determines how packets are forwarded:
+- **node:** (default) Application-level forwarding using Node.js
+- **nftables:** Kernel-level forwarding using Linux NFTables (requires root privileges)
+
+**NFTables Options:**
+When using `forwardingEngine: 'nftables'`, you can configure:
+```typescript
+interface INfTablesOptions {
+  protocol?: 'tcp' | 'udp' | 'all';
+  preserveSourceIP?: boolean;
+  maxRate?: string;              // Rate limiting (e.g., '100mbps')
+  priority?: number;             // QoS priority
+  tableName?: string;           // Custom NFTables table name
+  useIPSets?: boolean;          // Use IP sets for performance
+  useAdvancedNAT?: boolean;     // Use connection tracking
+}
+```
+
 **Redirect Action:**
 When `type: 'redirect'`, the client is redirected:
 ```typescript
@@ -459,6 +504,35 @@ Routes with higher priority values are matched first, allowing you to create spe
   priority: 100,
   tags: ['api', 'secure', 'internal']
 }
+
+// Example with NFTables forwarding engine
+{
+  match: {
+    ports: [80, 443],
+    domains: 'high-traffic.example.com'
+  },
+  action: {
+    type: 'forward',
+    target: {
+      host: 'backend-server',
+      port: 8080
+    },
+    forwardingEngine: 'nftables',  // Use kernel-level forwarding
+    nftables: {
+      protocol: 'tcp',
+      preserveSourceIP: true,
+      maxRate: '1gbps',
+      useIPSets: true
+    },
+    security: {
+      ipAllowList: ['10.0.0.*'],
+      blockedIps: ['malicious.ip.range.*']
+    }
+  },
+  name: 'High Performance NFTables Route',
+  description: 'Kernel-level forwarding for maximum performance',
+  priority: 150
+}
 ```
 
 ### Using Helper Functions
@@ -489,6 +563,8 @@ Available helper functions:
 - `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
+- `createNfTablesRoute()` - Create a high-performance NFTables route
+- `createNfTablesTerminateRoute()` - Create an NFTables route with TLS termination
 - `createPortRange()` - Helper to create port range configurations
 - `createSecurityConfig()` - Helper to create security configuration objects
 - `createBlockRoute()` - Create a route to block specific traffic
@@ -589,6 +665,16 @@ Available helper functions:
    await proxy.removeListeningPort(8081);
    ```
 
+9. **High-Performance NFTables Routing**
+   ```typescript
+   // Use kernel-level packet forwarding for maximum performance
+   createNfTablesRoute('high-traffic.example.com', { host: 'backend', port: 8080 }, {
+     ports: 80,
+     preserveSourceIP: true,
+     maxRate: '1gbps'
+   })
+   ```
+
 ## Other Components
 
 While SmartProxy provides a unified API for most needs, you can also use individual components:
@@ -694,16 +780,137 @@ const redirect = new SslRedirect(80);
 await redirect.start();
 ```
 
-## Migration to v16.0.0
+## NFTables Integration
+
+SmartProxy v18.0.0 includes full integration with Linux NFTables for high-performance kernel-level packet forwarding. NFTables operates directly in the Linux kernel, providing much better performance than user-space proxying for high-traffic scenarios.
+
+### When to Use NFTables
+
+NFTables routing is ideal for:
+- High-traffic TCP/UDP forwarding where performance is critical
+- Port forwarding scenarios where you need minimal latency
+- Load balancing across multiple backend servers
+- Security filtering with IP allowlists/blocklists at kernel level
+
+### Requirements
+
+NFTables support requires:
+- Linux operating system with NFTables installed
+- Root or sudo permissions to configure NFTables rules
+- NFTables kernel modules loaded
+
+### NFTables Route Configuration
+
+Use the NFTables helper functions to create high-performance routes:
+
+```typescript
+import { SmartProxy, createNfTablesRoute, createNfTablesTerminateRoute } from '@push.rocks/smartproxy';
+
+const proxy = new SmartProxy({
+  routes: [
+    // Basic TCP forwarding with NFTables
+    createNfTablesRoute('tcp-forward', {
+      host: 'backend-server',
+      port: 8080
+    }, {
+      ports: 80,
+      protocol: 'tcp'
+    }),
+
+    // NFTables with IP filtering
+    createNfTablesRoute('secure-tcp', {
+      host: 'secure-backend',
+      port: 8443
+    }, {
+      ports: 443,
+      ipAllowList: ['10.0.0.*', '192.168.1.*'],
+      preserveSourceIP: true
+    }),
+
+    // NFTables with QoS (rate limiting)
+    createNfTablesRoute('limited-service', {
+      host: 'api-server',
+      port: 3000
+    }, {
+      ports: 8080,
+      maxRate: '50mbps',
+      priority: 1
+    }),
+
+    // NFTables TLS termination
+    createNfTablesTerminateRoute('https-nftables', {
+      host: 'backend',
+      port: 8080
+    }, {
+      ports: 443,
+      certificate: 'auto',
+      useAdvancedNAT: true
+    })
+  ]
+});
+
+await proxy.start();
+```
+
+### NFTables Route Options
+
+The NFTables integration supports these options:
+
+- `protocol`: 'tcp' | 'udp' | 'all' - Protocol to forward
+- `preserveSourceIP`: boolean - Preserve client IP for backend
+- `ipAllowList`: string[] - Allow only these IPs (glob patterns)
+- `ipBlockList`: string[] - Block these IPs (glob patterns)
+- `maxRate`: string - Rate limit (e.g., '100mbps', '1gbps')
+- `priority`: number - QoS priority level
+- `tableName`: string - Custom NFTables table name
+- `useIPSets`: boolean - Use IP sets for better performance
+- `useAdvancedNAT`: boolean - Enable connection tracking
+
+### NFTables Status Monitoring
+
+You can monitor the status of NFTables rules:
+
+```typescript
+// Get status of all NFTables rules
+const nftStatus = await proxy.getNfTablesStatus();
+
+// Status includes:
+// - active: boolean
+// - ruleCount: { total, added, removed }
+// - packetStats: { forwarded, dropped }
+// - lastUpdate: Date
+```
+
+### Performance Considerations
+
+NFTables provides significantly better performance than application-level proxying:
+- Operates at kernel level with minimal overhead
+- Can handle millions of packets per second
+- Direct packet forwarding without copying to userspace
+- Hardware offload support on compatible network cards
+
+### Limitations
 
-Version 16.0.0 completes the migration to a fully unified route-based configuration system with improved helper functions:
+NFTables routing has some limitations:
+- Cannot modify HTTP headers or content
+- Limited to basic NAT and forwarding operations
+- Requires root permissions
+- Linux-only (not available on Windows/macOS)
+- No WebSocket message inspection
+
+For scenarios requiring application-level features (header manipulation, WebSocket handling, etc.), use the standard SmartProxy routes without NFTables.
+
+## Migration to v18.0.0
+
+Version 18.0.0 continues the evolution with NFTables integration while maintaining the unified route-based configuration system:
 
 ### Key Changes
 
-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
+1. **NFTables Integration**: High-performance kernel-level packet forwarding for Linux systems
+2. **Pure Route-Based API**: The configuration now exclusively uses the match/action pattern with no legacy interfaces
+3. **Improved Helper Functions**: Enhanced helper functions with cleaner parameter signatures
+4. **Removed Legacy Support**: Legacy domain-based APIs have been completely removed
+5. **More Route Pattern Helpers**: Additional helper functions for common routing patterns including NFTables routes
 
 ### Migration Example
 
@@ -723,7 +930,7 @@ const proxy = new SmartProxy({
 });
 ```
 
-**Current Configuration (v16.0.0)**:
+**Current Configuration (v18.0.0)**:
 ```typescript
 import { SmartProxy, createHttpsTerminateRoute } from '@push.rocks/smartproxy';
 
@@ -1212,6 +1419,13 @@ NetworkProxy now supports full route-based configuration including:
 - Use higher priority for block routes to ensure they take precedence
 - Enable `enableDetailedLogging` or `enableTlsDebugLogging` for debugging
 
+### NFTables Integration
+- Ensure NFTables is installed: `apt install nftables` or `yum install nftables`
+- Verify root/sudo permissions for NFTables operations
+- Check NFTables service is running: `systemctl status nftables`
+- For debugging, check the NFTables rules: `nft list ruleset`
+- Monitor NFTables rule status: `await proxy.getNfTablesStatus()`
+
 ### TLS/Certificates
 - For certificate issues, check the ACME settings and domain validation
 - Ensure domains are publicly accessible for Let's Encrypt validation