smartproxy/readme.hints.md

SmartProxy Development Hints

Byte Tracking and Metrics

Double Counting Issue (Fixed)

Problem: Initial data chunks were being counted twice in the byte tracking:

1. Once when stored in pendingData in setupDirectConnection()
2. Again when the data flowed through bidirectional forwarding

Solution: Removed the byte counting when storing initial chunks. Bytes are now only counted when they actually flow through the setupBidirectionalForwarding() callbacks.

HttpProxy Metrics (Fixed)

Problem: HttpProxy forwarding was updating connection record byte counts but not calling metricsCollector.recordBytes(), resulting in missing throughput data.

Solution: Added metricsCollector.recordBytes() calls to the HttpProxy bidirectional forwarding callbacks.

Metrics Architecture

The metrics system has three layers:

1. Connection Records (record.bytesReceived/bytesSent): Track total bytes per connection
2. ThroughputTracker: Accumulates bytes between samples for rate calculations (bytes/second)
3. connectionByteTrackers: Track bytes per connection with timestamps for per-route/IP metrics

Total byte counts come from connection records only, preventing double counting.

Connection Cleanup

Zombie Connection Detection

The connection manager performs comprehensive zombie detection every 10 seconds:

• Full zombies: Both incoming and outgoing sockets destroyed but connection not cleaned up
• Half zombies: One socket destroyed, grace period expired (5 minutes for TLS, 30 seconds for non-TLS)
• Stuck connections: Data received but none sent back after threshold (5 minutes for TLS, 60 seconds for non-TLS)

Cleanup Queue

Connections are cleaned up through a batched queue system:

• Batch size: 100 connections
• Processing triggered immediately when batch size reached
• Otherwise processed after 100ms delay
• Prevents overwhelming the system during mass disconnections

Keep-Alive Handling

Keep-alive connections receive special treatment based on keepAliveTreatment setting:

• standard: Normal timeout applies
• extended: Timeout multiplied by keepAliveInactivityMultiplier (default 6x)
• immortal: No timeout, connections persist indefinitely

PROXY Protocol

The system supports both receiving and sending PROXY protocol:

• Receiving: Automatically detected from trusted proxy IPs (configured in proxyIPs)
• Sending: Enabled per-route or globally via sendProxyProtocol setting
• Real client IP is preserved and used for all connection tracking and security checks