@push.rocks/smartproxy 19.5.19 → 19.5.20

package/readme.hints.md

@@ -661,4 +661,192 @@ 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