@push.rocks/smartproxy 19.6.2 → 19.6.7

package/readme.monitoring.md

@@ -1,202 +0,0 @@
-# Production Connection Monitoring
-
-This document explains how to use the ProductionConnectionMonitor to diagnose connection accumulation issues in real-time.
-
-## Quick Start
-
-```typescript
-import ProductionConnectionMonitor from './.nogit/debug/production-connection-monitor.js';
-
-// After starting your proxy
-const monitor = new ProductionConnectionMonitor(proxy);
-monitor.start(5000); // Check every 5 seconds
-
-// The monitor will automatically capture diagnostics when:
-// - Connections exceed 50 (default threshold)
-// - Sudden spike of 20+ connections occurs
-// - You manually call monitor.forceCaptureNow()
-```
-
-## What Gets Captured
-
-When accumulation is detected, the monitor saves a JSON file with:
-
-### Connection Details
-- Socket states (destroyed, readable, writable, readyState)
-- Connection age and activity timestamps
-- Data transfer statistics (bytes sent/received)
-- Target host and port information
-- Keep-alive status
-- Event listener counts
-
-### System State
-- Memory usage
-- Event loop lag
-- Connection count trends
-- Termination statistics
-
-## Reading Diagnostic Files
-
-Files are saved to `.nogit/connection-diagnostics/` with names like:
-```
-accumulation_2025-06-07T20-20-43-733Z_force_capture.json
-```
-
-### Key Fields to Check
-
-1. **Socket States**
-   ```json
-   "incomingState": {
-     "destroyed": false,
-     "readable": true,
-     "writable": true,
-     "readyState": "open"
-   }
-   ```
-   - Both destroyed = zombie connection
-   - One destroyed = half-zombie
-   - Both alive but old = potential stuck connection
-
-2. **Data Transfer**
-   ```json
-   "bytesReceived": 36,
-   "bytesSent": 0,
-   "timeSinceLastActivity": 60000
-   ```
-   - No bytes sent back = stuck connection
-   - High bytes but old = slow backend
-   - No activity = idle connection
-
-3. **Connection Flags**
-   ```json
-   "hasReceivedInitialData": false,
-   "hasKeepAlive": true,
-   "connectionClosed": false
-   ```
-   - hasReceivedInitialData=false on non-TLS = immediate routing
-   - hasKeepAlive=true = extended timeout applies
-   - connectionClosed=false = still tracked
-
-## Common Patterns
-
-### 1. Hanging Backend Pattern
-```json
-{
-  "bytesReceived": 36,
-  "bytesSent": 0,
-  "age": 120000,
-  "targetHost": "backend.example.com",
-  "incomingState": { "destroyed": false },
-  "outgoingState": { "destroyed": false }
-}
-```
-**Fix**: The stuck connection detection (60s timeout) should clean these up.
-
-### 2. Zombie Connection Pattern
-```json
-{
-  "incomingState": { "destroyed": true },
-  "outgoingState": { "destroyed": true },
-  "connectionClosed": false
-}
-```
-**Fix**: The zombie detection should clean these up within 30s.
-
-### 3. Event Listener Leak Pattern
-```json
-{
-  "incomingListeners": {
-    "data": 15,
-    "error": 20,
-    "close": 18
-  }
-}
-```
-**Issue**: Event listeners accumulating, potential memory leak.
-
-### 4. No Outgoing Socket Pattern
-```json
-{
-  "outgoingState": { "exists": false },
-  "connectionClosed": false,
-  "age": 5000
-}
-```
-**Issue**: Connection setup failed but cleanup didn't trigger.
-
-## Forcing Diagnostic Capture
-
-To capture current state immediately:
-```typescript
-monitor.forceCaptureNow();
-```
-
-This is useful when you notice accumulation starting.
-
-## Automated Analysis
-
-The monitor automatically analyzes patterns and logs:
-- Zombie/half-zombie counts
-- Stuck connection counts
-- Old connection counts
-- Memory usage
-- Recommendations
-
-## Integration Example
-
-```typescript
-// In your proxy startup script
-import { SmartProxy } from '@push.rocks/smartproxy';
-import ProductionConnectionMonitor from './production-connection-monitor.js';
-
-async function startProxyWithMonitoring() {
-  const proxy = new SmartProxy({
-    // your config
-  });
-  
-  await proxy.start();
-  
-  // Start monitoring
-  const monitor = new ProductionConnectionMonitor(proxy);
-  monitor.start(5000);
-  
-  // Optional: Capture on specific events
-  process.on('SIGUSR1', () => {
-    console.log('Manual diagnostic capture triggered');
-    monitor.forceCaptureNow();
-  });
-  
-  // Graceful shutdown
-  process.on('SIGTERM', async () => {
-    monitor.stop();
-    await proxy.stop();
-    process.exit(0);
-  });
-}
-```
-
-## Troubleshooting
-
-### Monitor Not Detecting Accumulation
-- Check threshold settings (default: 50 connections)
-- Reduce check interval for faster detection
-- Use forceCaptureNow() to capture current state
-
-### Too Many False Positives
-- Increase accumulation threshold
-- Increase spike threshold
-- Adjust check interval
-
-### Missing Diagnostic Data
-- Ensure output directory exists and is writable
-- Check disk space
-- Verify process has write permissions
-
-## Next Steps
-
-1. Deploy the monitor to production
-2. Wait for accumulation to occur
-3. Share diagnostic files for analysis
-4. Apply targeted fixes based on patterns found
-
-The diagnostic data will reveal the exact state of connections when accumulation occurs, enabling precise fixes for your specific scenario.

package/readme.proxy-chain-summary.md

@@ -1,112 +0,0 @@
-# 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
-
-```typescript
-// 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.