@push.rocks/smartproxy 19.6.1 → 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.