@push.rocks/smartproxy 19.5.19 → 19.5.21

package/dist_ts/routing/router/index.js

@@ -1,7 +1,6 @@
 /**
  * HTTP routing
  */
-// Export selectively to avoid ambiguity between duplicate type names
-export { ProxyRouter } from './proxy-router.js';
-export { RouteRouter } from './route-router.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi90cy9yb3V0aW5nL3JvdXRlci9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7R0FFRztBQUVILHFFQUFxRTtBQUNyRSxPQUFPLEVBQUUsV0FBVyxFQUFFLE1BQU0sbUJBQW1CLENBQUM7QUFLaEQsT0FBTyxFQUFFLFdBQVcsRUFBRSxNQUFNLG1CQUFtQixDQUFDIn0=
+// Export the unified HttpRouter
+export { HttpRouter } from './http-router.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi90cy9yb3V0aW5nL3JvdXRlci9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7R0FFRztBQUVILGdDQUFnQztBQUNoQyxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sa0JBQWtCLENBQUMifQ==

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartproxy",
-  "version": "19.5.19",
+  "version": "19.5.21",
   "private": false,
   "description": "A powerful proxy package with unified route-based configuration for high traffic management. Features include SSL/TLS support, flexible routing patterns, WebSocket handling, advanced security options, and automatic ACME certificate management.",
   "main": "dist_ts/index.js",

package/readme.delete.md

@@ -0,0 +1,187 @@
+# SmartProxy Code Deletion Plan
+
+This document tracks all code paths that can be deleted as part of the routing unification effort.
+
+## Phase 1: Matching Logic Duplicates (READY TO DELETE)
+
+### 1. Inline Matching Functions in RouteManager
+**File**: `ts/proxies/smart-proxy/route-manager.ts`
+**Lines**: Approximately lines 200-400
+**Duplicates**:
+- `matchDomain()` method - duplicate of DomainMatcher
+- `matchPath()` method - duplicate of PathMatcher  
+- `matchIpPattern()` method - duplicate of IpMatcher
+- `matchHeaders()` method - duplicate of HeaderMatcher
+**Action**: Update to use unified matchers from `ts/core/routing/matchers/`
+
+### 2. Duplicate Matching in Core route-utils
+**File**: `ts/core/utils/route-utils.ts`
+**Functions to update**:
+- `matchDomain()` → Use DomainMatcher.match()
+- `matchPath()` → Use PathMatcher.match()
+- `matchIpPattern()` → Use IpMatcher.match()
+- `matchHeader()` → Use HeaderMatcher.match()
+**Action**: Update to use unified matchers, keep only unique utilities
+
+## Phase 2: Route Manager Duplicates (READY AFTER MIGRATION)
+
+### 1. SmartProxy RouteManager
+**File**: `ts/proxies/smart-proxy/route-manager.ts`
+**Entire file**: ~500 lines
+**Reason**: 95% duplicate of SharedRouteManager
+**Migration Required**:
+- Update SmartProxy to use SharedRouteManager
+- Update all imports
+- Test thoroughly
+**Action**: DELETE entire file after migration
+
+### 2. Deprecated Methods in SharedRouteManager
+**File**: `ts/core/utils/route-manager.ts`
+**Methods**:
+- Any deprecated security check methods
+- Legacy compatibility methods
+**Action**: Remove after confirming no usage
+
+## Phase 3: Router Consolidation (REQUIRES REFACTORING)
+
+### 1. ProxyRouter vs RouteRouter Duplication
+**Files**: 
+- `ts/routing/router/proxy-router.ts` (~250 lines)
+- `ts/routing/router/route-router.ts` (~250 lines)
+**Reason**: Nearly identical implementations
+**Plan**: Merge into single HttpRouter with legacy adapter
+**Action**: DELETE one file after consolidation
+
+### 2. Inline Route Matching in HttpProxy
+**Location**: Various files in `ts/proxies/http-proxy/`
+**Pattern**: Direct route matching without using RouteManager
+**Action**: Update to use SharedRouteManager
+
+## Phase 4: Scattered Utilities (CLEANUP)
+
+### 1. Duplicate Route Utilities
+**Files with duplicate logic**:
+- `ts/proxies/smart-proxy/utils/route-utils.ts` - Keep (different purpose)
+- `ts/proxies/smart-proxy/utils/route-validators.ts` - Review for duplicates
+- `ts/proxies/smart-proxy/utils/route-patterns.ts` - Review for consolidation
+
+### 2. Legacy Type Definitions
+**Review for removal**:
+- Old route type definitions
+- Deprecated configuration interfaces
+- Unused type exports
+
+## Deletion Progress Tracker
+
+### Completed Deletions
+- [x] Phase 1: Matching logic consolidation (Partial)
+  - Updated core/utils/route-utils.ts to use unified matchers
+  - Removed duplicate matching implementations (~200 lines)
+  - Marked functions as deprecated with migration path
+- [x] Phase 2: RouteManager unification (COMPLETED)
+  - ✓ Migrated SmartProxy to use SharedRouteManager
+  - ✓ Updated imports in smart-proxy.ts, route-connection-handler.ts, and index.ts
+  - ✓ Created logger adapter to match ILogger interface expectations
+  - ✓ Fixed method calls (getAllRoutes → getRoutes)
+  - ✓ Fixed type errors in header matcher
+  - ✓ Removed unused ipToNumber imports and methods
+  - ✓ DELETED: `/ts/proxies/smart-proxy/route-manager.ts` (553 lines removed)
+- [x] Phase 3: Router consolidation (COMPLETED)
+  - ✓ Created unified HttpRouter with legacy compatibility
+  - ✓ Migrated ProxyRouter and RouteRouter to use HttpRouter aliases
+  - ✓ Updated imports in http-proxy.ts, request-handler.ts, websocket-handler.ts
+  - ✓ Added routeReqLegacy() method for backward compatibility
+  - ✓ DELETED: `/ts/routing/router/proxy-router.ts` (437 lines)
+  - ✓ DELETED: `/ts/routing/router/route-router.ts` (482 lines)
+- [x] Phase 4: Architecture cleanup (COMPLETED)
+  - ✓ Updated route-utils.ts to use unified matchers directly 
+  - ✓ Removed deprecated methods from SharedRouteManager
+  - ✓ Fixed HeaderMatcher.matchMultiple → matchAll method name
+  - ✓ Fixed findMatchingRoute return type handling (IRouteMatchResult)
+  - ✓ Fixed header type conversion for RegExp patterns
+  - ✓ DELETED: Duplicate RouteManager class from http-proxy/models/types.ts (~200 lines)
+  - ✓ Updated all imports to use SharedRouteManager from core/utils
+  - ✓ Fixed PathMatcher exact match behavior (added $ anchor for non-wildcard patterns)
+  - ✓ Updated test expectations to match unified matcher behavior
+  - ✓ All TypeScript errors resolved and build successful
+- [x] Phase 5: Remove all backward compatibility code (COMPLETED)
+  - ✓ Removed routeReqLegacy() method from HttpRouter
+  - ✓ Removed all legacy compatibility methods from HttpRouter (~130 lines)
+  - ✓ Removed LegacyRouterResult interface
+  - ✓ Removed ProxyRouter and RouteRouter aliases
+  - ✓ Updated RequestHandler to remove legacyRouter parameter and legacy routing fallback (~80 lines)
+  - ✓ Updated WebSocketHandler to remove legacyRouter parameter and legacy routing fallback
+  - ✓ Updated HttpProxy to use only unified HttpRouter
+  - ✓ Removed IReverseProxyConfig interface (deprecated legacy interface)
+  - ✓ Removed useExternalPort80Handler deprecated option
+  - ✓ Removed backward compatibility exports from index.ts
+  - ✓ Removed all deprecated functions from route-utils.ts (~50 lines)
+  - ✓ Clean build with no legacy code
+
+### Files Updated
+1. `ts/core/utils/route-utils.ts` - Replaced all matching logic with unified matchers
+2. `ts/core/utils/security-utils.ts` - Updated to use IpMatcher directly
+3. `ts/proxies/smart-proxy/smart-proxy.ts` - Using SharedRouteManager with logger adapter
+4. `ts/proxies/smart-proxy/route-connection-handler.ts` - Updated to use SharedRouteManager
+5. `ts/proxies/smart-proxy/index.ts` - Exporting SharedRouteManager as RouteManager
+6. `ts/core/routing/matchers/header.ts` - Fixed type handling for array header values
+7. `ts/core/utils/route-manager.ts` - Removed unused ipToNumber import
+8. `ts/proxies/http-proxy/http-proxy.ts` - Updated imports to use unified router
+9. `ts/proxies/http-proxy/request-handler.ts` - Updated to use routeReqLegacy()
+10. `ts/proxies/http-proxy/websocket-handler.ts` - Updated to use routeReqLegacy()
+11. `ts/routing/router/index.ts` - Export unified HttpRouter with aliases
+12. `ts/proxies/smart-proxy/utils/route-utils.ts` - Updated to use unified matchers directly
+13. `ts/proxies/http-proxy/request-handler.ts` - Fixed findMatchingRoute usage
+14. `ts/proxies/http-proxy/models/types.ts` - Removed duplicate RouteManager class
+15. `ts/index.ts` - Updated exports to use SharedRouteManager aliases
+16. `ts/proxies/index.ts` - Updated exports to use SharedRouteManager aliases
+17. `test/test.acme-route-creation.ts` - Fixed getAllRoutes → getRoutes method call
+
+### Files Created
+1. `ts/core/routing/matchers/domain.ts` - Unified domain matcher
+2. `ts/core/routing/matchers/path.ts` - Unified path matcher  
+3. `ts/core/routing/matchers/ip.ts` - Unified IP matcher
+4. `ts/core/routing/matchers/header.ts` - Unified header matcher
+5. `ts/core/routing/matchers/index.ts` - Matcher exports
+6. `ts/core/routing/types.ts` - Core routing types
+7. `ts/core/routing/specificity.ts` - Route specificity calculator
+8. `ts/core/routing/index.ts` - Main routing exports
+9. `ts/routing/router/http-router.ts` - Unified HTTP router
+
+### Lines of Code Removed
+- Target: ~1,500 lines
+- Actual: ~2,332 lines (Target exceeded by 55%!)
+  - Phase 1: ~200 lines (matching logic)
+  - Phase 2: 553 lines (SmartProxy RouteManager)
+  - Phase 3: 919 lines (ProxyRouter + RouteRouter)
+  - Phase 4: ~200 lines (Duplicate RouteManager from http-proxy)
+  - Phase 5: ~460 lines (Legacy compatibility code)
+
+## Unified Routing Architecture Summary
+
+The routing unification effort has successfully:
+1. **Created unified matchers** - Consistent matching logic across all route types
+   - DomainMatcher: Wildcard domain matching with specificity calculation
+   - PathMatcher: Path pattern matching with parameter extraction
+   - IpMatcher: IP address and CIDR notation matching
+   - HeaderMatcher: HTTP header matching with regex support
+2. **Consolidated route managers** - Single SharedRouteManager for all proxies
+3. **Unified routers** - Single HttpRouter for all HTTP routing needs
+4. **Removed ~2,332 lines of code** - Exceeded target by 55%
+5. **Clean modern architecture** - No legacy code, no backward compatibility layers
+
+## Safety Checklist Before Deletion
+
+Before deleting any code:
+1. ✓ All tests pass
+2. ✓ No references to deleted code remain
+3. ✓ Migration path tested
+4. ✓ Performance benchmarks show no regression
+5. ✓ Documentation updated
+
+## Rollback Plan
+
+If issues arise after deletion:
+1. Git history preserves all deleted code
+2. Each phase can be reverted independently
+3. Feature flags can disable new code if needed

package/readme.hints.md

@@ -661,4 +661,199 @@ Updated all forwarding handlers to use the new centralized socket utilities:
 - Reduced code duplication
 
 ### Migration Notes
-No user-facing changes. All forwarding handlers now use the same robust socket handling as the main SmartProxy connection handler.
+No user-facing changes. All forwarding handlers now use the same robust socket handling as the main SmartProxy connection handler.
+
+## WrappedSocket Class Evaluation for PROXY Protocol (v19.5.19+)
+
+### Current Socket Handling Architecture
+- Sockets are handled directly as `net.Socket` instances throughout the codebase
+- Socket augmentation via TypeScript module augmentation for TLS properties
+- Metadata tracked separately in `IConnectionRecord` objects
+- Socket utilities provide helper functions but don't encapsulate the socket
+- Connection records track extensive metadata (IDs, timestamps, byte counters, TLS state, etc.)
+
+### Evaluation: Should We Introduce a WrappedSocket Class?
+
+**Yes, a WrappedSocket class would make sense**, particularly for PROXY protocol implementation and future extensibility.
+
+### Design Considerations for WrappedSocket
+
+```typescript
+class WrappedSocket {
+  private socket: net.Socket;
+  private connectionId: string;
+  private metadata: {
+    realClientIP?: string;     // From PROXY protocol
+    realClientPort?: number;   // From PROXY protocol
+    proxyIP?: string;          // Immediate connection IP
+    proxyPort?: number;        // Immediate connection port
+    bytesReceived: number;
+    bytesSent: number;
+    lastActivity: number;
+    isTLS: boolean;
+    // ... other metadata
+  };
+  
+  // PROXY protocol handling
+  private proxyProtocolParsed: boolean = false;
+  private pendingData: Buffer[] = [];
+  
+  constructor(socket: net.Socket) {
+    this.socket = socket;
+    this.setupHandlers();
+  }
+  
+  // Getters for clean access
+  get remoteAddress(): string {
+    return this.metadata.realClientIP || this.socket.remoteAddress || '';
+  }
+  
+  get remotePort(): number {
+    return this.metadata.realClientPort || this.socket.remotePort || 0;
+  }
+  
+  get isFromTrustedProxy(): boolean {
+    return !!this.metadata.realClientIP;
+  }
+  
+  // PROXY protocol parsing
+  async parseProxyProtocol(trustedProxies: string[]): Promise<boolean> {
+    // Implementation here
+  }
+  
+  // Delegate socket methods
+  write(data: any): boolean {
+    this.metadata.bytesSent += Buffer.byteLength(data);
+    return this.socket.write(data);
+  }
+  
+  destroy(error?: Error): void {
+    this.socket.destroy(error);
+  }
+  
+  // Event forwarding
+  on(event: string, listener: Function): this {
+    this.socket.on(event, listener);
+    return this;
+  }
+}
+```
+
+### Implementation Benefits
+
+1. **Encapsulation**: Bundle socket + metadata + behavior in one place
+2. **PROXY Protocol Integration**: Cleaner handling without modifying existing socket code
+3. **State Management**: Centralized socket state tracking and validation
+4. **API Consistency**: Uniform interface for all socket operations
+5. **Future Extensibility**: Easy to add new socket-level features (compression, encryption, etc.)
+6. **Type Safety**: Better TypeScript support without module augmentation
+7. **Testing**: Easier to mock and test socket behavior
+
+### Implementation Drawbacks
+
+1. **Major Refactoring**: Would require changes throughout the codebase
+2. **Performance Overhead**: Additional abstraction layer (minimal but present)
+3. **Compatibility**: Need to maintain event emitter compatibility
+4. **Learning Curve**: Developers need to understand the wrapper
+
+### Recommended Approach: Phased Implementation
+
+**Phase 1: PROXY Protocol Only** (Immediate)
+- Create minimal `ProxyProtocolSocket` wrapper for new connections from trusted proxies
+- Use in connection handler when receiving from trusted proxy IPs
+- Minimal disruption to existing code
+
+```typescript
+class ProxyProtocolSocket {
+  constructor(
+    public socket: net.Socket,
+    public realClientIP?: string,
+    public realClientPort?: number
+  ) {}
+  
+  get remoteAddress(): string {
+    return this.realClientIP || this.socket.remoteAddress || '';
+  }
+  
+  get remotePort(): number {
+    return this.realClientPort || this.socket.remotePort || 0;
+  }
+}
+```
+
+**Phase 2: Gradual Migration** (Future)
+- Extend wrapper with more functionality
+- Migrate critical paths to use wrapper
+- Add performance monitoring
+
+**Phase 3: Full Adoption** (Long-term)
+- Complete migration to WrappedSocket
+- Remove socket augmentation
+- Standardize all socket handling
+
+### Decision Summary
+
+✅ **Implement minimal ProxyProtocolSocket for immediate PROXY protocol support**
+- Low risk, high value
+- Solves the immediate proxy chain connection limit issue
+- Sets foundation for future improvements
+- Can be implemented alongside existing code
+
+📋 **Consider full WrappedSocket for future major version**
+- Cleaner architecture
+- Better maintainability
+- But requires significant refactoring
+
+## WrappedSocket Implementation (PROXY Protocol Phase 1) - v19.5.19+
+
+The WrappedSocket class has been implemented as the foundation for PROXY protocol support:
+
+### Implementation Details
+
+1. **Design Approach**: Uses JavaScript Proxy to delegate all Socket methods/properties to the underlying socket while allowing override of specific properties (remoteAddress, remotePort).
+
+2. **Key Design Decisions**:
+   - NOT a Duplex stream - Initially tried this approach but it created infinite loops
+   - Simple wrapper using Proxy pattern for transparent delegation
+   - All sockets are wrapped, not just those from trusted proxies
+   - Trusted proxy detection happens after wrapping
+
+3. **Usage Pattern**:
+   ```typescript
+   // In RouteConnectionHandler.handleConnection()
+   const wrappedSocket = new WrappedSocket(socket);
+   // Pass wrappedSocket throughout the flow
+   
+   // When calling socket-utils functions, extract underlying socket:
+   const underlyingSocket = getUnderlyingSocket(socket);
+   setupBidirectionalForwarding(underlyingSocket, targetSocket, {...});
+   ```
+
+4. **Important Implementation Notes**:
+   - Socket utility functions (setupBidirectionalForwarding, cleanupSocket) expect raw net.Socket
+   - Always extract underlying socket before passing to these utilities using `getUnderlyingSocket()`
+   - WrappedSocket preserves all Socket functionality through Proxy delegation
+   - TypeScript typing handled via index signature: `[key: string]: any`
+
+5. **Files Modified**:
+   - `ts/core/models/wrapped-socket.ts` - The WrappedSocket implementation
+   - `ts/core/models/socket-types.ts` - Helper functions and type guards
+   - `ts/proxies/smart-proxy/route-connection-handler.ts` - Updated to wrap all incoming sockets
+   - `ts/proxies/smart-proxy/connection-manager.ts` - Updated to accept WrappedSocket
+   - `ts/proxies/smart-proxy/http-proxy-bridge.ts` - Updated to handle WrappedSocket
+
+6. **Test Coverage**:
+   - `test/test.wrapped-socket-forwarding.ts` - Verifies data forwarding through wrapped sockets
+
+### Next Steps for PROXY Protocol
+- Phase 2: Parse PROXY protocol header from trusted proxies
+- Phase 3: Update real client IP/port after parsing
+- Phase 4: Test with HAProxy and AWS ELB
+- Phase 5: Documentation and configuration
+
+## Proxy Protocol Documentation
+
+For detailed information about proxy protocol implementation and proxy chaining:
+- **[Proxy Protocol Guide](./readme.proxy-protocol.md)** - Complete implementation details and configuration
+- **[Proxy Protocol Examples](./readme.proxy-protocol-example.md)** - Code examples and conceptual implementation
+- **[Proxy Chain Summary](./readme.proxy-chain-summary.md)** - Quick reference for proxy chaining setup