smartproxy/readme.proxy-chain-summary.md

SmartProxy: Proxy Protocol and Proxy Chaining Summary

Quick Summary

SmartProxy supports proxy chaining through the WrappedSocket infrastructure, which is designed to handle PROXY protocol for preserving real client IP addresses across multiple proxy layers. While the infrastructure is in place (v19.5.19+), the actual PROXY protocol parsing is not yet implemented.

Current State

✅ What's Implemented

• WrappedSocket class - Foundation for proxy protocol support
• Proxy IP configuration - proxyIPs setting to define trusted proxies
• Socket wrapping - All incoming connections wrapped automatically
• Connection tracking - Real client IP tracking in connection records
• Test infrastructure - Tests for proxy chaining scenarios

❌ What's Missing

• PROXY protocol v1 parsing - Header parsing not implemented
• PROXY protocol v2 support - Binary format not supported
• Automatic header generation - Must be manually implemented
• Production testing - No HAProxy/AWS ELB compatibility tests

Key Files

Core Implementation

• ts/core/models/wrapped-socket.ts - WrappedSocket class
• ts/core/models/socket-types.ts - Helper functions
• ts/proxies/smart-proxy/route-connection-handler.ts - Connection handling
• ts/proxies/smart-proxy/models/interfaces.ts - Configuration interfaces

Tests

• test/test.wrapped-socket.ts - WrappedSocket unit tests
• test/test.proxy-chain-simple.node.ts - Basic proxy chain test
• test/test.proxy-chaining-accumulation.node.ts - Connection leak tests

Documentation

• readme.proxy-protocol.md - Detailed implementation guide
• readme.proxy-protocol-example.md - Code examples and future implementation
• readme.hints.md - Project overview with WrappedSocket notes

Quick Configuration Example

// Outer proxy (internet-facing)
const outerProxy = new SmartProxy({
  sendProxyProtocol: true, // Will send PROXY protocol (when implemented)
  routes: [{
    name: 'forward-to-inner',
    match: { ports: 443 },
    action: {
      type: 'forward',
      target: { host: 'inner-proxy.local', port: 443 },
      tls: { mode: 'passthrough' }
    }
  }]
});

// Inner proxy (backend-facing)
const innerProxy = new SmartProxy({
  proxyIPs: ['outer-proxy.local'], // Trust the outer proxy
  acceptProxyProtocol: true,        // Will parse PROXY protocol (when implemented)
  routes: [{
    name: 'forward-to-backend',
    match: { ports: 443, domains: 'api.example.com' },
    action: {
      type: 'forward',
      target: { host: 'backend.local', port: 8080 },
      tls: { mode: 'terminate' }
    }
  }]
});

How It Works (Conceptually)

1. Client connects to Outer Proxy
2. Outer Proxy wraps socket in WrappedSocket
3. Outer Proxy forwards to Inner Proxy
   • Would prepend: PROXY TCP4 <client-ip> <proxy-ip> <client-port> <proxy-port>\r\n
4. Inner Proxy receives connection from trusted proxy
5. Inner Proxy would parse PROXY protocol header
6. Inner Proxy updates WrappedSocket with real client IP
7. Backend receives connection with preserved client information

Important Notes

Connection Cleanup

The fix for proxy chain connection accumulation (v19.5.14+) changed the default socket behavior:

• Before: Half-open connections supported by default (caused accumulation)
• After: Both sockets close when one closes (prevents accumulation)
• Override: Set enableHalfOpen: true if half-open needed

Security

• Only parse PROXY protocol from IPs listed in proxyIPs
• Never use 0.0.0.0/0 as a trusted proxy range
• Each proxy in chain must explicitly trust the previous proxy

Testing

Use the test files as reference implementations:

• Simple chains: test.proxy-chain-simple.node.ts
• Connection leaks: test.proxy-chaining-accumulation.node.ts
• Rapid reconnects: test.rapid-retry-cleanup.node.ts

Next Steps

To fully implement PROXY protocol support:

1. Implement the parser in ProxyProtocolParser class
2. Integrate parser into handleConnection method
3. Add header generation to setupDirectConnection
4. Test with real proxies (HAProxy, nginx, AWS ELB)
5. Add PROXY protocol v2 support for better performance

See readme.proxy-protocol-example.md for detailed implementation examples.