Implement PROXY protocol v1 support in SmartProxy

- Added ProxyProtocolParser class for parsing and generating PROXY protocol v1 headers.
- Integrated PROXY protocol parsing into RouteConnectionHandler for handling incoming connections from trusted proxies.
- Implemented WrappedSocket class to encapsulate real client information.
- Configured SmartProxy to accept and send PROXY protocol headers in routing actions.
- Developed comprehensive unit tests for PROXY protocol parsing and generation.
- Documented usage patterns, configuration, and best practices for proxy chaining scenarios.
- Added security and performance considerations for PROXY protocol implementation.

readme.plan.md

@@ -98,26 +98,32 @@ This phase creates the socket wrapper infrastructure that all subsequent phases
 
 **Deliverables**: ✅ Working WrappedSocket that can wrap any socket and provide transparent access to client info.
 
-#### Phase 2: PROXY Protocol Parser - DEPENDS ON PHASE 1
+#### Phase 2: PROXY Protocol Parser - ✅ COMPLETED (v19.5.21)
 Only after WrappedSocket is working can we add protocol parsing.
 
-1. Create `ProxyProtocolParser` class in `ts/core/utils/proxy-protocol.ts`
-2. Implement v1 text format parsing
-3. Add validation and error handling
-4. Integrate parser to work WITH WrappedSocket (not into it)
+1. ✅ Created `ProxyProtocolParser` class in `ts/core/utils/proxy-protocol.ts`
+2. ✅ Implemented v1 text format parsing with full validation
+3. ✅ Added comprehensive error handling and IP validation
+4. ✅ Integrated parser to work WITH WrappedSocket in RouteConnectionHandler
 
-#### Phase 3: Connection Handler Integration - DEPENDS ON PHASES 1 & 2
+**Deliverables**: ✅ Working PROXY protocol v1 parser that validates headers, extracts client info, and handles both TCP4 and TCP6 protocols.
+
+#### Phase 3: Connection Handler Integration - ✅ COMPLETED (v19.5.21)
 1. ✅ Modify `RouteConnectionHandler` to create WrappedSocket for all connections
-2. Check if connection is from trusted proxy IP
-3. If trusted, attempt to parse PROXY protocol header
-4. Update wrapped socket with real client info
-5. Continue normal connection handling with wrapped socket
+2. ✅ Check if connection is from trusted proxy IP
+3. ✅ If trusted, attempt to parse PROXY protocol header
+4. ✅ Update wrapped socket with real client info
+5. ✅ Continue normal connection handling with wrapped socket
 
-#### Phase 4: Outbound PROXY Protocol - DEPENDS ON PHASES 1-3
-1. Add PROXY header generation in `setupDirectConnection`
-2. Make it configurable per route
-3. Send header immediately after TCP connection
-4. Use ProxyProtocolSocket for outbound connections too
+**Deliverables**: ✅ RouteConnectionHandler now parses PROXY protocol from trusted proxies and updates connection records with real client info.
+
+#### Phase 4: Outbound PROXY Protocol - ✅ COMPLETED (v19.5.21)
+1. ✅ Add PROXY header generation in `setupDirectConnection`
+2. ✅ Make it configurable per route via `sendProxyProtocol` option
+3. ✅ Send header immediately after TCP connection
+4. ✅ Added remotePort tracking to connection records
+
+**Deliverables**: ✅ SmartProxy can now send PROXY protocol headers to backend servers when configured, preserving client IP through proxy chains.
 
 #### Phase 5: Security & Validation - FINAL PHASE
 1. Validate PROXY headers strictly
@@ -293,11 +299,10 @@ if (wrappedSocket instanceof ProxyProtocolSocket) {
 
 ### 5. Configuration Examples
 
-#### Basic Setup
+#### Basic Setup (IMPLEMENTED ✅)
 ```typescript
 // Outer proxy - sends PROXY protocol
 const outerProxy = new SmartProxy({
-  ports: [443],
   routes: [{
     name: 'to-inner-proxy',
     match: { ports: 443 },
@@ -311,9 +316,8 @@ const outerProxy = new SmartProxy({
 
 // Inner proxy - accepts PROXY protocol from outer proxy
 const innerProxy = new SmartProxy({
-  ports: [443],
   proxyIPs: ['212.95.99.130'],  // Outer proxy IP
-  // acceptProxyProtocol: true is automatic for proxyIPs
+  acceptProxyProtocol: true,     // Optional - defaults to true when proxyIPs is set
   routes: [{
     name: 'to-backend',
     match: { ports: 443 },