feat(forwarding): Add unified forwarding system docs and tests; update build script and .gitignore

docs/forwarding-system.md

@@ -0,0 +1,242 @@
+# SmartProxy Unified Forwarding System
+
+This document describes the new unified forwarding system in SmartProxy.
+
+## Overview
+
+The forwarding system provides a clean, use-case driven approach to configuring different types of traffic forwarding. It replaces the previous 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.
+
+## Configuration
+
+### 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 { helpers } from '../smartproxy/forwarding/index.js';
+
+// HTTP-only
+const httpConfig = helpers.httpOnly('localhost', 3000);
+
+// HTTPS termination to HTTP
+const terminateToHttpConfig = helpers.tlsTerminateToHttp('localhost', 3000);
+
+// HTTPS termination to HTTPS
+const terminateToHttpsConfig = helpers.tlsTerminateToHttps('localhost', 8443);
+
+// HTTPS passthrough (SNI)
+const passthroughConfig = helpers.sniPassthrough('localhost', 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}'
+      }
+    }
+  }
+}
+```
+
+## DomainManager
+
+The `DomainManager` class manages domains and their forwarding handlers:
+
+```typescript
+import { DomainManager, createDomainConfig, helpers } from '../smartproxy/forwarding/index.js';
+
+// Create the domain manager
+const domainManager = new DomainManager();
+
+// Add a domain
+await domainManager.addDomainConfig(
+  createDomainConfig('example.com', helpers.httpOnly('localhost', 3000))
+);
+
+// Handle a connection
+domainManager.handleConnection('example.com', socket);
+
+// Handle an HTTP request
+domainManager.handleHttpRequest('example.com', req, res);
+```
+
+## Usage Examples
+
+### Basic HTTP Server
+
+```typescript
+{
+  domains: ['example.com'],
+  forwarding: {
+    type: 'http-only',
+    target: {
+      host: 'localhost',
+      port: 3000
+    }
+  }
+}
+```
+
+### HTTPS Termination with HTTP Backend
+
+```typescript
+{
+  domains: ['secure.example.com'],
+  forwarding: {
+    type: 'https-terminate-to-http',
+    target: {
+      host: 'localhost',
+      port: 3000
+    },
+    acme: {
+      production: true  // Use production Let's Encrypt
+    }
+  }
+}
+```
+
+### HTTPS Termination with HTTPS Backend
+
+```typescript
+{
+  domains: ['secure-backend.example.com'],
+  forwarding: {
+    type: 'https-terminate-to-https',
+    target: {
+      host: 'internal-api',
+      port: 8443
+    },
+    http: {
+      redirectToHttps: true  // Redirect HTTP requests to HTTPS
+    }
+  }
+}
+```
+
+### SNI Passthrough
+
+```typescript
+{
+  domains: ['passthrough.example.com'],
+  forwarding: {
+    type: 'https-passthrough',
+    target: {
+      host: '10.0.0.5',
+      port: 443
+    }
+  }
+}
+```
+
+### Load Balancing
+
+```typescript
+{
+  domains: ['api.example.com'],
+  forwarding: {
+    type: 'https-terminate-to-https',
+    target: {
+      host: ['10.0.0.10', '10.0.0.11', '10.0.0.12'], // Round-robin
+      port: 8443
+    }
+  }
+}
+```
+
+## Integration with SmartProxy
+
+The unified forwarding system integrates with SmartProxy by replacing the existing domain configuration mechanism. The `DomainManager` handles all domain matching and forwarding, while the individual forwarding handlers handle the connections and requests.
+
+The system is designed to be used in SmartProxy's `ConnectionHandler` and in the `Port80Handler` for HTTP traffic.
+
+## Testing
+
+See the `test.forwarding.ts` file for examples of how to test the forwarding system.
+
+## Migration
+
+When migrating from the older configuration system, map the existing configuration to the appropriate forwarding type:
+
+1. HTTP forwarding → `http-only`
+2. SNI forwarding → `https-passthrough`
+3. NetworkProxy with HTTP backend → `https-terminate-to-http`
+4. NetworkProxy with HTTPS backend → `https-terminate-to-https`
+
+## Extensibility
+
+The forwarding system is designed to be extensible:
+
+1. New forwarding types can be added by:
+   - Adding a new type to `ForwardingType`
+   - Creating a new handler class
+   - Adding the handler to `ForwardingHandlerFactory`
+
+2. Existing types can be extended with new options by updating the interface and handler implementations.
+
+## Implementation Details
+
+The system uses a factory pattern to create the appropriate handler for each forwarding type. Each handler extends a base `ForwardingHandler` class that provides common functionality.
+
+The `DomainManager` manages the domains and their handlers, and delegates connections and requests to the appropriate handler.
+
+## Performance Considerations
+
+- The system uses a map for fast domain lookups
+- Wildcard domains are supported through pattern matching
+- Handlers are reused for multiple domains with the same configuration