@push.rocks/smartproxy 19.6.2 → 19.6.6

package/readme.routing.md

@@ -1,341 +0,0 @@
-# SmartProxy Routing Architecture Unification Plan
-
-## Overview
-This document analyzes the current state of routing in SmartProxy, identifies redundancies and inconsistencies, and proposes a unified architecture.
-
-## Current State Analysis
-
-### 1. Multiple Route Manager Implementations
-
-#### 1.1 Core SharedRouteManager (`ts/core/utils/route-manager.ts`)
-- **Purpose**: Designed as a shared component for SmartProxy and NetworkProxy
-- **Features**:
-  - Port mapping and expansion (e.g., `[80, 443]` → individual routes)
-  - Comprehensive route matching (domain, path, IP, headers, TLS)
-  - Route validation and conflict detection
-  - Event emitter for route changes
-  - Detailed logging support
-- **Status**: Well-designed but underutilized
-
-#### 1.2 SmartProxy RouteManager (`ts/proxies/smart-proxy/route-manager.ts`)
-- **Purpose**: SmartProxy-specific route management
-- **Issues**:
-  - 95% duplicate code from SharedRouteManager
-  - Only difference is using `ISmartProxyOptions` instead of generic interface
-  - Contains deprecated security methods
-  - Unnecessary code duplication
-- **Status**: Should be removed in favor of SharedRouteManager
-
-#### 1.3 HttpProxy Route Management (`ts/proxies/http-proxy/`)
-- **Purpose**: HTTP-specific routing
-- **Implementation**: Minimal, inline route matching
-- **Status**: Could benefit from SharedRouteManager
-
-### 2. Multiple Router Implementations
-
-#### 2.1 ProxyRouter (`ts/routing/router/proxy-router.ts`)
-- **Purpose**: Legacy compatibility with `IReverseProxyConfig`
-- **Features**: Domain-based routing with path patterns
-- **Used by**: HttpProxy for backward compatibility
-
-#### 2.2 RouteRouter (`ts/routing/router/route-router.ts`)
-- **Purpose**: Modern routing with `IRouteConfig`
-- **Features**: Nearly identical to ProxyRouter
-- **Issues**: Code duplication with ProxyRouter
-
-### 3. Scattered Route Utilities
-
-#### 3.1 Core route-utils (`ts/core/utils/route-utils.ts`)
-- **Purpose**: Shared matching functions
-- **Features**: Domain, path, IP, CIDR matching
-- **Status**: Well-implemented, should be the single source
-
-#### 3.2 SmartProxy route-utils (`ts/proxies/smart-proxy/utils/route-utils.ts`)
-- **Purpose**: Route configuration utilities
-- **Features**: Different scope - config merging, not pattern matching
-- **Status**: Keep separate as it serves different purpose
-
-### 4. Other Route-Related Files
-- `route-patterns.ts`: Constants for route patterns
-- `route-validators.ts`: Route configuration validation
-- `route-helpers.ts`: Additional utilities
-- `route-connection-handler.ts`: Connection routing logic
-
-## Problems Identified
-
-### 1. Code Duplication
-- **SharedRouteManager vs SmartProxy RouteManager**: ~1000 lines of duplicate code
-- **ProxyRouter vs RouteRouter**: ~500 lines of duplicate code
-- **Matching logic**: Implemented in 4+ different places
-
-### 2. Inconsistent Implementations
-```typescript
-// Example: Domain matching appears in multiple places
-// 1. In route-utils.ts
-export function matchDomain(pattern: string, hostname: string): boolean
-
-// 2. In SmartProxy RouteManager
-private matchDomain(domain: string, hostname: string): boolean
-
-// 3. In ProxyRouter
-private matchesHostname(configName: string, hostname: string): boolean
-
-// 4. In RouteRouter
-private matchDomain(pattern: string, hostname: string): boolean
-```
-
-### 3. Unclear Separation of Concerns
-- Route Managers handle both storage AND matching
-- Routers also handle storage AND matching
-- No clear boundaries between layers
-
-### 4. Maintenance Burden
-- Bug fixes need to be applied in multiple places
-- New features must be implemented multiple times
-- Testing effort multiplied
-
-## Proposed Unified Architecture
-
-### Layer 1: Core Routing Components
-```
-ts/core/routing/
-├── types.ts              # All route-related types
-├── utils.ts              # All matching logic (consolidated)
-├── route-store.ts        # Route storage and indexing
-└── route-matcher.ts      # Route matching engine
-```
-
-### Layer 2: Route Management
-```
-ts/core/routing/
-└── route-manager.ts      # Single RouteManager for all proxies
-    - Uses RouteStore for storage
-    - Uses RouteMatcher for matching
-    - Provides high-level API
-```
-
-### Layer 3: HTTP Routing
-```
-ts/routing/
-└── http-router.ts        # Single HTTP router implementation
-    - Uses RouteManager for route lookup
-    - Handles HTTP-specific concerns
-    - Legacy adapter built-in
-```
-
-### Layer 4: Proxy Integration
-```
-ts/proxies/
-├── smart-proxy/
-│   └── (uses core RouteManager directly)
-├── http-proxy/
-│   └── (uses core RouteManager + HttpRouter)
-└── network-proxy/
-    └── (uses core RouteManager directly)
-```
-
-## Implementation Plan
-
-### Phase 1: Consolidate Matching Logic (Week 1)
-1. **Audit all matching implementations**
-   - Document differences in behavior
-   - Identify the most comprehensive implementation
-   - Create test suite covering all edge cases
-
-2. **Create unified matching module**
-   ```typescript
-   // ts/core/routing/matchers.ts
-   export class DomainMatcher {
-     static match(pattern: string, hostname: string): boolean
-   }
-   
-   export class PathMatcher {
-     static match(pattern: string, path: string): MatchResult
-   }
-   
-   export class IpMatcher {
-     static match(pattern: string, ip: string): boolean
-     static matchCidr(cidr: string, ip: string): boolean
-   }
-   ```
-
-3. **Update all components to use unified matchers**
-   - Replace local implementations
-   - Ensure backward compatibility
-   - Run comprehensive tests
-
-### Phase 2: Unify Route Managers (Week 2)
-1. **Enhance SharedRouteManager**
-   - Add any missing features from SmartProxy RouteManager
-   - Make it truly generic (no proxy-specific dependencies)
-   - Add adapter pattern for different options types
-
-2. **Migrate SmartProxy to use SharedRouteManager**
-   ```typescript
-   // Before
-   this.routeManager = new RouteManager(this.settings);
-   
-   // After
-   this.routeManager = new SharedRouteManager({
-     logger: this.settings.logger,
-     enableDetailedLogging: this.settings.enableDetailedLogging
-   });
-   ```
-
-3. **Remove duplicate RouteManager**
-   - Delete `ts/proxies/smart-proxy/route-manager.ts`
-   - Update all imports
-   - Verify all tests pass
-
-### Phase 3: Consolidate Routers (Week 3)
-1. **Create unified HttpRouter**
-   ```typescript
-   export class HttpRouter {
-     constructor(private routeManager: SharedRouteManager) {}
-     
-     // Modern interface
-     route(req: IncomingMessage): RouteResult
-     
-     // Legacy adapter
-     routeLegacy(config: IReverseProxyConfig): RouteResult
-   }
-   ```
-
-2. **Migrate HttpProxy**
-   - Replace both ProxyRouter and RouteRouter
-   - Use single HttpRouter with appropriate adapter
-   - Maintain backward compatibility
-
-3. **Clean up legacy code**
-   - Mark old interfaces as deprecated
-   - Add migration guides
-   - Plan removal in next major version
-
-### Phase 4: Architecture Cleanup (Week 4)
-1. **Reorganize file structure**
-   ```
-   ts/core/
-   ├── routing/
-   │   ├── index.ts
-   │   ├── types.ts
-   │   ├── matchers/
-   │   │   ├── domain.ts
-   │   │   ├── path.ts
-   │   │   ├── ip.ts
-   │   │   └── index.ts
-   │   ├── route-store.ts
-   │   ├── route-matcher.ts
-   │   └── route-manager.ts
-   └── utils/
-       └── (remove route-specific utils)
-   ```
-
-2. **Update documentation**
-   - Architecture diagrams
-   - Migration guides
-   - API documentation
-
-3. **Performance optimization**
-   - Add caching where beneficial
-   - Optimize hot paths
-   - Benchmark before/after
-
-## Migration Strategy
-
-### For SmartProxy RouteManager Users
-```typescript
-// Old way
-import { RouteManager } from './route-manager.js';
-const manager = new RouteManager(options);
-
-// New way
-import { SharedRouteManager as RouteManager } from '../core/utils/route-manager.js';
-const manager = new RouteManager({
-  logger: options.logger,
-  enableDetailedLogging: options.enableDetailedLogging
-});
-```
-
-### For Router Users
-```typescript
-// Old way
-const proxyRouter = new ProxyRouter();
-const routeRouter = new RouteRouter();
-
-// New way
-const router = new HttpRouter(routeManager);
-// Automatically handles both modern and legacy configs
-```
-
-## Success Metrics
-
-1. **Code Reduction**
-   - Target: Remove ~1,500 lines of duplicate code
-   - Measure: Lines of code before/after
-
-2. **Performance**
-   - Target: No regression in routing performance
-   - Measure: Benchmark route matching operations
-
-3. **Maintainability**
-   - Target: Single implementation for each concept
-   - Measure: Time to implement new features
-
-4. **Test Coverage**
-   - Target: 100% coverage of routing logic
-   - Measure: Coverage reports
-
-## Risks and Mitigations
-
-### Risk 1: Breaking Changes
-- **Mitigation**: Extensive adapter patterns and backward compatibility layers
-- **Testing**: Run all existing tests plus new integration tests
-
-### Risk 2: Performance Regression
-- **Mitigation**: Benchmark critical paths before changes
-- **Testing**: Load testing with production-like scenarios
-
-### Risk 3: Hidden Dependencies
-- **Mitigation**: Careful code analysis and dependency mapping
-- **Testing**: Integration tests across all proxy types
-
-## Long-term Vision
-
-### Future Enhancements
-1. **Route Caching**: LRU cache for frequently accessed routes
-2. **Route Indexing**: Trie-based indexing for faster domain matching
-3. **Route Priorities**: Explicit priority system instead of specificity
-4. **Dynamic Routes**: Support for runtime route modifications
-5. **Route Templates**: Reusable route configurations
-
-### API Evolution
-```typescript
-// Future unified routing API
-const routingEngine = new RoutingEngine({
-  stores: [fileStore, dbStore, dynamicStore],
-  matchers: [domainMatcher, pathMatcher, customMatcher],
-  cache: new LRUCache({ max: 1000 }),
-  indexes: {
-    domain: new TrieIndex(),
-    path: new RadixTree()
-  }
-});
-
-// Simple, powerful API
-const route = await routingEngine.findRoute({
-  domain: 'example.com',
-  path: '/api/v1/users',
-  ip: '192.168.1.1',
-  headers: { 'x-custom': 'value' }
-});
-```
-
-## Conclusion
-
-The current routing architecture has significant duplication and inconsistencies. By following this unification plan, we can:
-1. Reduce code by ~30%
-2. Improve maintainability
-3. Ensure consistent behavior
-4. Enable future enhancements
-
-The phased approach minimizes risk while delivering incremental value. Each phase is independently valuable and can be deployed separately.

package/readme.websocket-keepalive-config.md

@@ -1,140 +0,0 @@
-# WebSocket Keep-Alive Configuration Guide
-
-## Quick Fix for SNI Passthrough WebSocket Disconnections
-
-If your WebSocket connections are disconnecting every 30 seconds in SNI passthrough mode, here's the immediate solution:
-
-### Option 1: Extended Keep-Alive Treatment (Recommended)
-
-```typescript
-const proxy = new SmartProxy({
-  // Extend timeout for keep-alive connections
-  keepAliveTreatment: 'extended',
-  keepAliveInactivityMultiplier: 10, // 10x the base timeout
-  inactivityTimeout: 14400000, // 4 hours base (40 hours with multiplier)
-  
-  routes: [
-    {
-      name: 'websocket-passthrough',
-      match: { 
-        ports: 443, 
-        domains: ['ws.example.com', 'wss.example.com'] 
-      },
-      action: {
-        type: 'forward',
-        target: { host: 'backend', port: 443 },
-        tls: { mode: 'passthrough' }
-      }
-    }
-  ]
-});
-```
-
-### Option 2: Immortal Connections (Never Timeout)
-
-```typescript
-const proxy = new SmartProxy({
-  // Never timeout keep-alive connections
-  keepAliveTreatment: 'immortal',
-  
-  routes: [
-    // ... same as above
-  ]
-});
-```
-
-### Option 3: Per-Route Security Settings
-
-```typescript
-const proxy = new SmartProxy({
-  routes: [
-    {
-      name: 'websocket-passthrough',
-      match: { 
-        ports: 443, 
-        domains: ['ws.example.com'] 
-      },
-      action: {
-        type: 'forward',
-        target: { host: 'backend', port: 443 },
-        tls: { mode: 'passthrough' }
-      },
-      security: {
-        // Disable connection limits for this route
-        maxConnections: 0, // 0 = unlimited
-        maxConnectionsPerIP: 0 // 0 = unlimited
-      }
-    }
-  ]
-});
-```
-
-## Understanding the Issue
-
-### Why Connections Drop at 30 Seconds
-
-1. **WebSocket Heartbeat**: The HTTP proxy's WebSocket handler sends ping frames every 30 seconds
-2. **SNI Passthrough**: In passthrough mode, traffic is encrypted end-to-end
-3. **Can't Inject Pings**: The proxy can't inject ping frames into encrypted traffic
-4. **No Pong Response**: Client doesn't respond to pings that were never sent
-5. **Connection Terminated**: After 30 seconds, connection is marked inactive and closed
-
-### Why Grace Periods Were Too Short
-
-- Half-zombie detection: 30 seconds (now 5 minutes for TLS)
-- Stuck connection detection: 60 seconds (now 5 minutes for TLS)
-- These were too aggressive for encrypted long-lived connections
-
-## Long-Term Solution
-
-The fix involves:
-
-1. **Detecting SNI Passthrough**: Skip WebSocket heartbeat for passthrough connections
-2. **Longer Grace Periods**: 5-minute grace for encrypted connections
-3. **TCP Keep-Alive**: Rely on OS-level TCP keep-alive instead
-4. **Route-Aware Timeouts**: Different timeout strategies per route type
-
-## TCP Keep-Alive Configuration
-
-For best results, also configure TCP keep-alive at the OS level:
-
-### Linux
-```bash
-# /etc/sysctl.conf
-net.ipv4.tcp_keepalive_time = 600    # Start probes after 10 minutes
-net.ipv4.tcp_keepalive_intvl = 60    # Probe every minute
-net.ipv4.tcp_keepalive_probes = 9    # Drop after 9 failed probes
-```
-
-### Node.js Socket Options
-The proxy already enables TCP keep-alive on sockets:
-- Keep-alive is enabled by default
-- Initial delay can be configured via `keepAliveInitialDelay`
-
-## Monitoring
-
-Check your connections:
-
-```typescript
-const stats = proxy.getStats();
-console.log('Active connections:', stats.getActiveConnections());
-console.log('Connections by route:', stats.getConnectionsByRoute());
-
-// Monitor long-lived connections
-setInterval(() => {
-  const connections = proxy.connectionManager.getConnections();
-  for (const [id, conn] of connections) {
-    const age = Date.now() - conn.incomingStartTime;
-    if (age > 300000) { // 5+ minutes
-      console.log(`Long-lived connection: ${id}, age: ${age}ms, route: ${conn.routeName}`);
-    }
-  }
-}, 60000);
-```
-
-## Summary
-
-- **Immediate Fix**: Use `keepAliveTreatment: 'extended'` or `'immortal'`
-- **Applied Fix**: Increased grace periods for TLS connections to 5 minutes
-- **Best Practice**: Use SNI passthrough for WebSocket when you need end-to-end encryption
-- **Alternative**: Use TLS termination if you need application-level WebSocket features

package/readme.websocket-keepalive-fix.md

@@ -1,63 +0,0 @@
-# WebSocket Keep-Alive Fix for SNI Passthrough
-
-## Problem
-
-WebSocket connections in SNI passthrough mode are being disconnected every 30 seconds due to:
-
-1. **WebSocket Heartbeat**: The HTTP proxy's WebSocket handler performs heartbeat checks every 30 seconds using ping/pong frames. In SNI passthrough mode, these frames can't be injected into the encrypted stream, causing connections to be marked as inactive and terminated.
-
-2. **Half-Zombie Detection**: The connection manager's aggressive cleanup gives only 30 seconds grace period for connections where one socket is destroyed.
-
-## Solution
-
-For SNI passthrough connections:
-1. Disable WebSocket-specific heartbeat checking (they're handled as raw TCP)
-2. Rely on TCP keepalive settings instead
-3. Increase grace period for encrypted connections
-
-## Current Settings
-
-- Default inactivity timeout: 4 hours (14400000 ms)
-- Keep-alive multiplier for extended mode: 6x (24 hours)
-- WebSocket heartbeat interval: 30 seconds (problem!)
-- Half-zombie grace period: 30 seconds (too aggressive)
-
-## Recommended Configuration
-
-```typescript
-const proxy = new SmartProxy({
-  // Increase grace period for connection cleanup
-  inactivityTimeout: 14400000, // 4 hours default
-  keepAliveTreatment: 'extended', // or 'immortal' for no timeout
-  keepAliveInactivityMultiplier: 10, // 40 hours for keepalive connections
-  
-  // For routes with WebSocket over SNI passthrough
-  routes: [
-    {
-      name: 'websocket-passthrough',
-      match: { ports: 443, domains: 'ws.example.com' },
-      action: {
-        type: 'forward',
-        target: { host: 'backend', port: 443 },
-        tls: { mode: 'passthrough' },
-        // No WebSocket-specific config needed for passthrough
-      }
-    }
-  ]
-});
-```
-
-## Temporary Workaround
-
-Until a fix is implemented, you can:
-
-1. Use `keepAliveTreatment: 'immortal'` to disable timeout-based cleanup
-2. Increase the half-zombie grace period
-3. Use TCP keepalive at the OS level
-
-## Proper Fix Implementation
-
-1. Detect when a connection is SNI passthrough
-2. Skip WebSocket heartbeat for passthrough connections 
-3. Increase grace period for encrypted connections
-4. Rely on TCP keepalive instead of application-level ping/pong