BREAKING CHANGE(forwarding): Refactor unified forwarding API and remove redundant documentation. Removed docs/forwarding-system.md (its content is migrated into readme.md) and updated helper functions (e.g. replacing sniPassthrough with httpsPassthrough) to accept configuration objects. Legacy fields in domain configurations (allowedIPs, blockedIPs, useNetworkProxy, networkProxyPort, connectionTimeout) have been removed in favor of forwarding.security and advanced options. Tests and examples have been updated accordingly.

2025-05-09 15:39:15 +00:00
parent f00bae4631
commit 1a902a04fb
20 changed files with 441 additions and 434 deletions
--- a/readme.md
+++ b/readme.md
@ -6,6 +6,7 @@ A high-performance proxy toolkit for Node.js, offering:
 - Low-level port forwarding via nftables
 - HTTP-to-HTTPS and custom URL redirects
 - Advanced TCP/SNI-based proxying with IP filtering and rules
+- Unified forwarding configuration system for all proxy types

 ## Exports
 The following classes and interfaces are provided:
@ -23,11 +24,14 @@ The following classes and interfaces are provided:
  TCP/SNI-based proxy with dynamic routing, IP filtering, and unified certificates.
 - **SniHandler** (ts/smartproxy/classes.pp.snihandler.ts)
  Static utilities to extract SNI hostnames from TLS handshakes.
+- **Forwarding Handlers** (ts/smartproxy/forwarding/*.ts)
+  Unified forwarding handlers for different connection types (HTTP, HTTPS passthrough, TLS termination).
 - **Interfaces**
  - IPortProxySettings, IDomainConfig (ts/smartproxy/classes.pp.interfaces.ts)
  - INetworkProxyOptions (ts/networkproxy/classes.np.types.ts)
-  - IAcmeOptions, IDomainOptions, IForwardConfig (ts/common/types.ts)
+  - IAcmeOptions, IDomainOptions (ts/common/types.ts)
  - INfTableProxySettings (ts/nfttablesproxy/classes.nftablesproxy.ts)
+  - IForwardConfig, ForwardingType (ts/smartproxy/types/forwarding.types.ts)

 ## Installation
 Install via npm:
@ -134,16 +138,37 @@ await nft.stop();
 ### 5. TCP/SNI Proxy (SmartProxy)
 ```typescript
 import { SmartProxy } from '@push.rocks/smartproxy';
+import { createDomainConfig, httpOnly, tlsTerminateToHttp, httpsPassthrough } from '@push.rocks/smartproxy';

 const smart = new SmartProxy({
  fromPort: 443,
  toPort: 8443,
  domainConfigs: [
-    {
-      domains: ['example.com', '*.example.com'],
-      allowedIPs: ['*'],
-      targetIPs: ['127.0.0.1'],
-    }
+    // HTTPS passthrough example
+    createDomainConfig(['example.com', '*.example.com'],
+      httpsPassthrough({
+        target: {
+          host: '127.0.0.1',
+          port: 443
+        },
+        security: {
+          allowedIps: ['*']
+        }
+      })
+    ),
+    // HTTPS termination example
+    createDomainConfig('secure.example.com',
+      tlsTerminateToHttp({
+        target: {
+          host: 'localhost',
+          port: 3000
+        },
+        acme: {
+          enabled: true,
+          production: true
+        }
+      })
+    )
  ],
  sniEnabled: true
 });
@ -386,6 +411,126 @@ Listen for certificate events via EventEmitter:

 Provide a `certProvisionFunction(domain)` in SmartProxy settings to supply static certs or return `'http01'`.

+## Unified Forwarding System
+
+The SmartProxy Unified Forwarding System provides a clean, use-case driven approach to configuring different types of traffic forwarding. It replaces disparate configuration mechanisms with a unified interface.
+
+### Forwarding Types
+
+The system supports four primary forwarding types:
+
+1. **HTTP-only (`http-only`)**: Forwards HTTP traffic to a backend server.
+2. **HTTPS Passthrough (`https-passthrough`)**: Passes through raw TLS traffic without termination (SNI forwarding).
+3. **HTTPS Termination to HTTP (`https-terminate-to-http`)**: Terminates TLS and forwards the decrypted traffic to an HTTP backend.
+4. **HTTPS Termination to HTTPS (`https-terminate-to-https`)**: Terminates TLS and creates a new TLS connection to an HTTPS backend.
+
+### Basic Configuration
+
+Each domain is configured with a forwarding type and target:
+
+```typescript
+{
+  domains: ['example.com'],
+  forwarding: {
+    type: 'http-only',
+    target: {
+      host: 'localhost',
+      port: 3000
+    }
+  }
+}
+```
+
+### Helper Functions
+
+Helper functions are provided for common configurations:
+
+```typescript
+import { createDomainConfig, httpOnly, tlsTerminateToHttp,
+         tlsTerminateToHttps, httpsPassthrough } from '@push.rocks/smartproxy';
+
+// HTTP-only
+await domainManager.addDomainConfig(
+  createDomainConfig('example.com', httpOnly({
+    target: { host: 'localhost', port: 3000 }
+  }))
+);
+
+// HTTPS termination to HTTP
+await domainManager.addDomainConfig(
+  createDomainConfig('secure.example.com', tlsTerminateToHttp({
+    target: { host: 'localhost', port: 3000 },
+    acme: { production: true }
+  }))
+);
+
+// HTTPS termination to HTTPS
+await domainManager.addDomainConfig(
+  createDomainConfig('api.example.com', tlsTerminateToHttps({
+    target: { host: 'internal-api', port: 8443 },
+    http: { redirectToHttps: true }
+  }))
+);
+
+// HTTPS passthrough (SNI)
+await domainManager.addDomainConfig(
+  createDomainConfig('passthrough.example.com', httpsPassthrough({
+    target: { host: '10.0.0.5', port: 443 }
+  }))
+);
+```
+
+### Advanced Configuration
+
+For more complex scenarios, additional options can be specified:
+
+```typescript
+{
+  domains: ['api.example.com'],
+  forwarding: {
+    type: 'https-terminate-to-https',
+    target: {
+      host: ['10.0.0.10', '10.0.0.11'], // Round-robin load balancing
+      port: 8443
+    },
+    http: {
+      enabled: true,
+      redirectToHttps: true
+    },
+    https: {
+      // Custom certificate instead of ACME-provisioned
+      customCert: {
+        key: '-----BEGIN PRIVATE KEY-----\n...',
+        cert: '-----BEGIN CERTIFICATE-----\n...'
+      }
+    },
+    security: {
+      allowedIps: ['10.0.0.*', '192.168.1.*'],
+      blockedIps: ['1.2.3.4'],
+      maxConnections: 100
+    },
+    advanced: {
+      timeout: 30000,
+      headers: {
+        'X-Forwarded-For': '{clientIp}',
+        'X-Original-Host': '{sni}'
+      }
+    }
+  }
+}
+```
+
+### Extended Configuration Options
+
+#### IForwardConfig
+- `type`: 'http-only' | 'https-passthrough' | 'https-terminate-to-http' | 'https-terminate-to-https'
+- `target`: { host: string | string[], port: number }
+- `http?`: { enabled?: boolean, redirectToHttps?: boolean, headers?: Record<string, string> }
+- `https?`: { customCert?: { key: string, cert: string }, forwardSni?: boolean }
+- `acme?`: { enabled?: boolean, maintenance?: boolean, production?: boolean, forwardChallenges?: { host: string, port: number, useTls?: boolean } }
+- `security?`: { allowedIps?: string[], blockedIps?: string[], maxConnections?: number }
+- `advanced?`: { portRanges?: Array<{ from: number, to: number }>, networkProxyPort?: number, keepAlive?: boolean, timeout?: number, headers?: Record<string, string> }
+
 ## Configuration Options

 ### NetworkProxy (INetworkProxyOptions)
@ -425,12 +570,14 @@ Provide a `certProvisionFunction(domain)` in SmartProxy settings to supply stati

 ### SmartProxy (IPortProxySettings)
 - `fromPort`, `toPort` (number)
- `domainConfigs` (IDomainConfig[])
- `sniEnabled`, `defaultAllowedIPs`, `preserveSourceIP` (booleans)
+- `domainConfigs` (IDomainConfig[]) - Using unified forwarding configuration
+- `sniEnabled`, `preserveSourceIP` (booleans)
+- `defaultAllowedIPs`, `defaultBlockedIPs` (string[]) - Default IP allowlists/blocklists
 - Timeouts: `initialDataTimeout`, `socketTimeout`, `inactivityTimeout`, etc.
 - Socket opts: `noDelay`, `keepAlive`, `enableKeepAliveProbes`
 - `acme` (IAcmeOptions), `certProvisionFunction` (callback)
 - `useNetworkProxy` (number[]), `networkProxyPort` (number)
+- `globalPortRanges` (Array<{ from: number; to: number }>)

 ## Troubleshooting

@ -455,6 +602,9 @@ Provide a `certProvisionFunction(domain)` in SmartProxy settings to supply stati
 - Increase `initialDataTimeout`/`maxPendingDataSize` for large ClientHello
 - Enable `enableTlsDebugLogging` to trace handshake
 - Ensure `allowSessionTicket` and fragmentation support for resumption
+- Double-check forwarding configuration to ensure correct `type` for your use case
+- Use helper functions like `httpOnly()`, `httpsPassthrough()`, etc. to create correct configurations
+- For IP filtering issues, check the `security.allowedIps` and `security.blockedIps` settings

 ## License and Legal Information