diff --git a/readme.md b/readme.md index 16642cf..7c615a3 100644 --- a/readme.md +++ b/readme.md @@ -665,6 +665,661 @@ redirect: { } ``` +## Forwarding Modes Guide + +This section provides a comprehensive reference for all forwarding modes available in SmartProxy, helping you choose the right configuration for your use case. + +### Visual Overview + +```mermaid +graph TD + A[Incoming Traffic] --> B{Action Type?} + + B -->|forward| C{TLS Mode?} + B -->|socket-handler| D[Custom Handler] + + C -->|terminate| E[Decrypt TLS] + C -->|passthrough| F[Forward Encrypted] + C -->|terminate-and-reencrypt| G[Decrypt & Re-encrypt] + C -->|none/HTTP| H[Forward HTTP] + + E --> I{Engine?} + F --> I + G --> I + H --> I + + I -->|node| J[Node.js Processing] + I -->|nftables| K[Kernel NAT] + + J --> L[Backend] + K --> L + D --> M[Custom Logic] + + style B fill:#f9f,stroke:#333,stroke-width:2px + style C fill:#bbf,stroke:#333,stroke-width:2px + style I fill:#bfb,stroke:#333,stroke-width:2px +``` + +### Overview + +SmartProxy offers flexible traffic forwarding through combinations of: +- **Action Types**: How to handle matched traffic +- **TLS Modes**: How to handle HTTPS/TLS connections +- **Forwarding Engines**: Where packet processing occurs + +### Quick Reference + +#### Modern Route-Based Configuration + +| Use Case | Action Type | TLS Mode | Engine | Performance | Security | +|----------|------------|----------|---------|-------------|----------| +| HTTP web server | `forward` | N/A | `node` | Good | Basic | +| HTTPS web server (inspect traffic) | `forward` | `terminate` | `node` | Good | Full inspection | +| HTTPS passthrough (no inspection) | `forward` | `passthrough` | `node` | Better | End-to-end encryption | +| HTTPS gateway (re-encrypt to backend) | `forward` | `terminate-and-reencrypt` | `node` | Moderate | Full control | +| High-performance TCP forwarding | `forward` | `passthrough` | `nftables` | Excellent | Basic | +| Custom protocol handling | `socket-handler` | N/A | `node` | Varies | Custom | + +#### Legacy Forwarding Types (Deprecated) + +| Legacy Type | Modern Equivalent | +|------------|------------------| +| `http-only` | `action.type: 'forward'` with port 80 | +| `https-passthrough` | `action.type: 'forward'` + `tls.mode: 'passthrough'` | +| `https-terminate-to-http` | `action.type: 'forward'` + `tls.mode: 'terminate'` | +| `https-terminate-to-https` | `action.type: 'forward'` + `tls.mode: 'terminate-and-reencrypt'` | + +### Forwarding Mode Categories + +#### 1. Action Types + +##### Forward Action +Routes traffic to a backend server. This is the most common action type. + +```typescript +{ + action: { + type: 'forward', + target: { + host: 'backend-server', + port: 8080 + } + } +} +``` + +##### Socket Handler Action +Provides custom handling for any TCP protocol. Used for specialized protocols or custom logic. + +```typescript +{ + action: { + type: 'socket-handler', + socketHandler: async (socket, context) => { + // Custom protocol implementation + } + } +} +``` + +#### 2. TLS Modes (for Forward Action) + +##### Passthrough Mode +- **What**: Forwards encrypted TLS traffic without decryption +- **When**: Backend handles its own TLS termination +- **Pros**: Maximum performance, true end-to-end encryption +- **Cons**: Cannot inspect or modify HTTPS traffic + +```mermaid +graph LR + Client -->|TLS| SmartProxy + SmartProxy -->|TLS| Backend + style SmartProxy fill:#f9f,stroke:#333,stroke-width:2px +``` + +##### Terminate Mode +- **What**: Decrypts TLS, forwards as plain HTTP +- **When**: Backend doesn't support HTTPS or you need to inspect traffic +- **Pros**: Can modify headers, inspect content, add security headers +- **Cons**: Backend connection is unencrypted + +```mermaid +graph LR + Client -->|TLS| SmartProxy + SmartProxy -->|HTTP| Backend + style SmartProxy fill:#f9f,stroke:#333,stroke-width:2px +``` + +##### Terminate-and-Reencrypt Mode +- **What**: Decrypts TLS, then creates new TLS connection to backend +- **When**: Need traffic inspection but backend requires HTTPS +- **Pros**: Full control while maintaining backend security +- **Cons**: Higher CPU usage, increased latency + +```mermaid +graph LR + Client -->|TLS| SmartProxy + SmartProxy -->|New TLS| Backend + style SmartProxy fill:#f9f,stroke:#333,stroke-width:2px +``` + +#### 3. Forwarding Engines + +##### Node.js Engine (Default) +- **Processing**: Application-level in Node.js event loop +- **Features**: Full protocol support, header manipulation, WebSockets +- **Performance**: Good for most use cases +- **Use when**: You need application-layer features + +##### NFTables Engine +- **Processing**: Kernel-level packet forwarding +- **Features**: Basic NAT, minimal overhead +- **Performance**: Excellent, near wire-speed +- **Use when**: Maximum performance is critical +- **Requirements**: Linux, root permissions, NFTables installed + +### Detailed Mode Explanations + +#### HTTP Forwarding (Port 80) + +Simple HTTP forwarding without encryption: + +```typescript +{ + match: { ports: 80, domains: 'example.com' }, + action: { + type: 'forward', + target: { host: 'localhost', port: 8080 } + } +} +``` + +**Data Flow**: Client → SmartProxy (HTTP) → Backend (HTTP) + +#### HTTPS with TLS Termination + +Decrypt HTTPS and forward as HTTP: + +```typescript +{ + match: { ports: 443, domains: 'secure.example.com' }, + action: { + type: 'forward', + target: { host: 'localhost', port: 8080 }, + tls: { + mode: 'terminate', + certificate: 'auto' // Use Let's Encrypt + } + } +} +``` + +**Data Flow**: Client → SmartProxy (HTTPS decrypt) → Backend (HTTP) + +#### HTTPS Passthrough + +Forward encrypted traffic without decryption: + +```typescript +{ + match: { ports: 443, domains: 'legacy.example.com' }, + action: { + type: 'forward', + target: { host: '192.168.1.10', port: 443 }, + tls: { + mode: 'passthrough' + } + } +} +``` + +**Data Flow**: Client → SmartProxy (TLS forwarding) → Backend (Original TLS) + +#### HTTPS Gateway (Terminate and Re-encrypt) + +Decrypt, inspect, then re-encrypt to backend: + +```typescript +{ + match: { ports: 443, domains: 'api.example.com' }, + action: { + type: 'forward', + target: { host: 'api-backend', port: 443 }, + tls: { + mode: 'terminate-and-reencrypt', + certificate: 'auto' + }, + advanced: { + headers: { + 'X-Forwarded-Proto': 'https', + 'X-Real-IP': '{clientIp}' + } + } + } +} +``` + +**Data Flow**: Client → SmartProxy (HTTPS decrypt) → SmartProxy (New HTTPS) → Backend + +#### High-Performance NFTables Forwarding + +Kernel-level forwarding for maximum performance: + +```typescript +{ + match: { ports: 443, domains: 'fast.example.com' }, + action: { + type: 'forward', + target: { host: 'backend', port: 443 }, + tls: { mode: 'passthrough' }, + forwardingEngine: 'nftables', + nftables: { + preserveSourceIP: true, + maxRate: '10gbps' + } + } +} +``` + +**Data Flow**: Client → Kernel (NFTables NAT) → Backend + +#### Custom Socket Handler + +Handle custom protocols or implement specialized logic: + +```typescript +{ + match: { ports: 9000, domains: 'custom.example.com' }, + action: { + type: 'socket-handler', + socketHandler: async (socket, context) => { + console.log(`Connection from ${context.clientIp}`); + + socket.write('Welcome to custom protocol server\n'); + + socket.on('data', (data) => { + // Handle custom protocol + const response = processCustomProtocol(data); + socket.write(response); + }); + } + } +} +``` + +### Decision Guide + +#### Choose HTTP Forwarding When: +- Backend only supports HTTP +- Internal services not exposed to internet +- Development/testing environments + +#### Choose HTTPS Termination When: +- Need to inspect/modify HTTP traffic +- Backend doesn't support HTTPS +- Want to add security headers +- Need to cache responses + +#### Choose HTTPS Passthrough When: +- Backend manages its own certificates +- Need true end-to-end encryption +- Compliance requires no MITM +- WebSocket connections to backend + +#### Choose HTTPS Terminate-and-Reencrypt When: +- Need traffic inspection AND backend requires HTTPS +- API gateway scenarios +- Adding authentication layers +- Different certificates for client/backend + +#### Choose NFTables Engine When: +- Handling 1Gbps+ traffic +- Thousands of concurrent connections +- Minimal latency is critical +- Don't need application-layer features + +#### Choose Socket Handler When: +- Implementing custom protocols +- Need fine-grained connection control +- Building protocol adapters +- Special authentication flows + +### Complete Examples + +#### Example 1: Complete Web Application + +```typescript +const proxy = new SmartProxy({ + routes: [ + // HTTP to HTTPS redirect + { + match: { ports: 80, domains: ['example.com', 'www.example.com'] }, + action: { + type: 'socket-handler', + socketHandler: SocketHandlers.httpRedirect('https://{domain}{path}') + } + }, + + // Main website with TLS termination + { + match: { ports: 443, domains: ['example.com', 'www.example.com'] }, + action: { + type: 'forward', + target: { host: 'web-backend', port: 3000 }, + tls: { + mode: 'terminate', + certificate: 'auto' + }, + websocket: { enabled: true } + } + }, + + // API with re-encryption + { + match: { ports: 443, domains: 'api.example.com' }, + action: { + type: 'forward', + target: { host: 'api-backend', port: 443 }, + tls: { + mode: 'terminate-and-reencrypt', + certificate: 'auto' + } + }, + security: { + ipAllowList: ['10.0.0.0/8'], + rateLimit: { + enabled: true, + maxRequests: 100, + window: 60 + } + } + } + ] +}); +``` + +#### Example 2: Multi-Mode Proxy Setup + +```typescript +const proxy = new SmartProxy({ + routes: [ + // Legacy app with passthrough + { + match: { ports: 443, domains: 'legacy.example.com' }, + action: { + type: 'forward', + target: { host: 'legacy-server', port: 443 }, + tls: { mode: 'passthrough' } + } + }, + + // High-performance streaming with NFTables + { + match: { ports: 8080, domains: 'stream.example.com' }, + action: { + type: 'forward', + target: { host: 'stream-backend', port: 8080 }, + forwardingEngine: 'nftables', + nftables: { + protocol: 'tcp', + preserveSourceIP: true + } + } + }, + + // Custom protocol handler + { + match: { ports: 9999 }, + action: { + type: 'socket-handler', + socketHandler: SocketHandlers.proxy('custom-backend', 9999) + } + } + ] +}); +``` + +### Performance Considerations + +#### Node.js Engine Performance + +| Metric | Typical Performance | +|--------|-------------------| +| Throughput | 1-10 Gbps | +| Connections | 10,000-50,000 concurrent | +| Latency | 1-5ms added | +| CPU Usage | Moderate | + +**Best for**: Most web applications, APIs, sites needing inspection + +#### NFTables Engine Performance + +| Metric | Typical Performance | +|--------|-------------------| +| Throughput | 10-100 Gbps | +| Connections | 100,000+ concurrent | +| Latency | <0.1ms added | +| CPU Usage | Minimal | + +**Best for**: High-traffic services, streaming, gaming, TCP forwarding + +#### Performance Tips + +1. **Use passthrough mode** when you don't need inspection +2. **Enable NFTables** for high-traffic services +3. **Terminate TLS only when necessary** - it adds CPU overhead +4. **Use connection pooling** for terminate-and-reencrypt mode +5. **Enable HTTP/2** for better multiplexing + +### Security Implications + +#### TLS Termination Security + +**Pros:** +- Inspect traffic for threats +- Add security headers +- Implement WAF rules +- Log requests for audit + +**Cons:** +- Proxy has access to decrypted data +- Requires secure certificate storage +- Potential compliance issues + +**Best Practices:** +- Use auto-renewal with Let's Encrypt +- Store certificates securely +- Implement proper access controls +- Use strong TLS configurations + +#### Passthrough Security + +**Pros:** +- True end-to-end encryption +- No MITM concerns +- Backend controls security + +**Cons:** +- Cannot inspect traffic +- Cannot add security headers +- Limited DDoS protection + +#### Socket Handler Security + +**Risks:** +- Custom code may have vulnerabilities +- Resource exhaustion possible +- Authentication bypass risks + +**Mitigations:** +```typescript +{ + action: { + type: 'socket-handler', + socketHandler: async (socket, context) => { + // Always validate and sanitize input + socket.on('data', (data) => { + if (data.length > MAX_SIZE) { + socket.destroy(); + return; + } + // Process safely... + }); + + // Set timeouts + socket.setTimeout(30000); + + // Rate limit connections + if (connectionsFromIP(context.clientIp) > 10) { + socket.destroy(); + } + } + } +} +``` + +### Migration from Legacy Types + +#### From `http-only` + +**Old:** +```typescript +{ + type: 'http-only', + target: { host: 'localhost', port: 8080 } +} +``` + +**New:** +```typescript +{ + match: { ports: 80, domains: 'example.com' }, + action: { + type: 'forward', + target: { host: 'localhost', port: 8080 } + } +} +``` + +#### From `https-passthrough` + +**Old:** +```typescript +{ + type: 'https-passthrough', + target: { host: 'backend', port: 443 } +} +``` + +**New:** +```typescript +{ + match: { ports: 443, domains: 'example.com' }, + action: { + type: 'forward', + target: { host: 'backend', port: 443 }, + tls: { mode: 'passthrough' } + } +} +``` + +#### From `https-terminate-to-http` + +**Old:** +```typescript +{ + type: 'https-terminate-to-http', + target: { host: 'localhost', port: 8080 }, + ssl: { /* certs */ } +} +``` + +**New:** +```typescript +{ + match: { ports: 443, domains: 'example.com' }, + action: { + type: 'forward', + target: { host: 'localhost', port: 8080 }, + tls: { + mode: 'terminate', + certificate: 'auto' // or provide cert/key + } + } +} +``` + +#### From `https-terminate-to-https` + +**Old:** +```typescript +{ + type: 'https-terminate-to-https', + target: { host: 'backend', port: 443 }, + ssl: { /* certs */ } +} +``` + +**New:** +```typescript +{ + match: { ports: 443, domains: 'example.com' }, + action: { + type: 'forward', + target: { host: 'backend', port: 443 }, + tls: { + mode: 'terminate-and-reencrypt', + certificate: 'auto' + } + } +} +``` + +### Helper Functions Quick Reference + +SmartProxy provides helper functions for common configurations: + +```typescript +// HTTP forwarding +createHttpRoute('example.com', { host: 'localhost', port: 8080 }) + +// HTTPS with termination +createHttpsTerminateRoute('secure.com', { host: 'localhost', port: 8080 }, { + certificate: 'auto' +}) + +// HTTPS passthrough +createHttpsPassthroughRoute('legacy.com', { host: 'backend', port: 443 }) + +// Complete HTTPS setup (includes HTTP redirect) +...createCompleteHttpsServer('example.com', { host: 'localhost', port: 8080 }, { + certificate: 'auto' +}) + +// NFTables high-performance +createNfTablesRoute('fast.com', { host: 'backend', port: 8080 }, { + ports: 80, + preserveSourceIP: true +}) + +// Custom socket handler +createSocketHandlerRoute('custom.com', 9000, async (socket, context) => { + // Handler implementation +}) +``` + +### Summary + +SmartProxy's forwarding modes provide flexibility for any proxy scenario: + +- **Simple HTTP/HTTPS forwarding** for most web applications +- **TLS passthrough** for end-to-end encryption +- **TLS termination** for traffic inspection and modification +- **NFTables** for extreme performance requirements +- **Socket handlers** for custom protocols + +Choose based on your security requirements, performance needs, and whether you need to inspect or modify traffic. The modern route-based configuration provides a consistent interface regardless of the forwarding mode you choose. + ### Route Metadata and Prioritization You can add metadata to routes to help with organization and control matching priority: