19.5.1

changelog.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 2025-05-29 - 19.5.1 - fix(socket-handler)
+Fix socket handler race condition by differentiating between async and sync handlers. Now, async socket handlers complete their setup before initial data is emitted, ensuring that no data is lost. Documentation and tests have been updated to reflect this change.
+
+- Added detailed explanation in readme.hints.md about the race condition issue, root cause, and solution implementation.
+- Provided a code snippet that checks if the socket handler returns a Promise and waits for its resolution before emitting initial data.
+- Updated tests (test.socket-handler-race.ts, test.socket-handler.simple.ts, test.socket-handler.ts) to verify correct behavior of async handlers.
+
+## 2025-05-28 - 19.5.0 - feat(socket-handler)
+Add socket-handler support for custom socket handling in SmartProxy
+
+- Introduce new action type 'socket-handler' in IRouteAction to allow users to provide a custom socket handler function.
+- Update the RouteConnectionHandler to detect 'socket-handler' actions and invoke the handler with the raw socket, giving full control to the user.
+- Provide optional context (such as route configuration, client IP, and port) to the socket handler if needed.
+- Add helper functions in route-helpers for creating socket handler routes and common patterns like echo, proxy, and line-based protocols.
+- Include a detailed implementation plan and usage examples in readme.plan.md.
+
+## 2025-05-28 - 19.4.3 - fix(smartproxy)
+Improve port binding intelligence and ACME challenge route management; update route configuration tests and dependency versions.
+
+- Bumped dev dependency versions in package.json (tsbuild from ^2.5.1 to ^2.6.4, tstest from ^1.9.0 to ^2.3.1, @types/node updated, smartfile from ^11.2.0 to ^11.2.5, smartlog from ^3.1.7 to ^3.1.8)
+- Removed readme.plan.md containing legacy development plan information
+- Normalized route configuration properties across tests (using 'ports' and 'domains' instead of legacy 'port' or 'domain')
+- Enhanced PortManager with reference counting and smarter port conflict detection to avoid redundant bindings
+- Refined ACME challenge route integration to merge with existing port bindings and improve error handling
+- Adjusted test expectations (e.g. using toEqual instead of toBe, and improved timeout handling) to align with current API changes
+
+## 2025-05-20 - 19.4.2 - fix(dependencies)
+Update dependency versions: upgrade @types/node to ^22.15.20 and @push.rocks/smartlog to ^3.1.7 in package.json
+
+- Bump @types/node from ^22.15.19 to ^22.15.20
+- Bump @push.rocks/smartlog from ^3.1.3 to ^3.1.7
+
 ## 2025-05-20 - 19.4.1 - fix(smartproxy)
 Bump @push.rocks/smartlog to ^3.1.3 and improve ACME port binding behavior in SmartProxy
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartproxy",
-  "version": "19.4.1",
+  "version": "19.5.1",
   "private": false,
   "description": "A powerful proxy package with unified route-based configuration for high traffic management. Features include SSL/TLS support, flexible routing patterns, WebSocket handling, advanced security options, and automatic ACME certificate management.",
   "main": "dist_ts/index.js",
@@ -15,10 +15,10 @@
     "buildDocs": "tsdoc"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^2.5.1",
+    "@git.zone/tsbuild": "^2.6.4",
     "@git.zone/tsrun": "^1.2.44",
-    "@git.zone/tstest": "^1.9.0",
-    "@types/node": "^22.15.19",
+    "@git.zone/tstest": "^2.3.1",
+    "@types/node": "^22.15.24",
     "typescript": "^5.8.3"
   },
   "dependencies": {
@@ -26,8 +26,8 @@
     "@push.rocks/smartacme": "^8.0.0",
     "@push.rocks/smartcrypto": "^2.0.4",
     "@push.rocks/smartdelay": "^3.0.5",
-    "@push.rocks/smartfile": "^11.2.0",
-    "@push.rocks/smartlog": "^3.1.3",
+    "@push.rocks/smartfile": "^11.2.5",
+    "@push.rocks/smartlog": "^3.1.8",
     "@push.rocks/smartnetwork": "^4.0.2",
     "@push.rocks/smartpromise": "^4.2.3",
     "@push.rocks/smartrequest": "^2.1.0",

readme.hints.md

@@ -155,4 +155,41 @@ Deferred certificate provisioning until after ports are ready:
 - `test/test.acme-timing-simple.ts` - Verifies proper timing sequence
 
 ### Migration
-Update to v19.3.9+, no configuration changes needed.
+Update to v19.3.9+, no configuration changes needed.
+
+## Socket Handler Race Condition Fix (v19.5.0)
+
+### Issue
+Initial data chunks were being emitted before async socket handlers had completed setup, causing data loss when handlers performed async operations before setting up data listeners.
+
+### Root Cause
+The `handleSocketHandlerAction` method was using `process.nextTick` to emit initial chunks regardless of whether the handler was sync or async. This created a race condition where async handlers might not have their listeners ready when the initial data was emitted.
+
+### Solution
+Differentiated between sync and async handlers:
+```typescript
+const result = route.action.socketHandler(socket);
+
+if (result instanceof Promise) {
+  // Async handler - wait for completion before emitting initial data
+  result.then(() => {
+    if (initialChunk && initialChunk.length > 0) {
+      socket.emit('data', initialChunk);
+    }
+  }).catch(/*...*/);
+} else {
+  // Sync handler - use process.nextTick as before
+  if (initialChunk && initialChunk.length > 0) {
+    process.nextTick(() => {
+      socket.emit('data', initialChunk);
+    });
+  }
+}
+```
+
+### Test Coverage
+- `test/test.socket-handler-race.ts` - Specifically tests async handlers with delayed listener setup
+- Verifies that initial data is received even when handler sets up listeners after async work
+
+### Usage Note
+Socket handlers require initial data from the client to trigger routing (not just a TLS handshake). Clients must send at least one byte of data for the handler to be invoked.

readme.plan.md

@@ -1,384 +1,316 @@
 # SmartProxy Development Plan
 
-## ACME Route Port Binding Intelligence Improvement
+## Implementation Plan: Socket Handler Function Support (Simplified) ✅ COMPLETED
 
-### Problem Statement
-Currently, SmartProxy has an issue with port binding conflicts between regular routes and ACME challenge routes. While SmartProxy is designed to support multiple routes sharing the same port (differentiated by host, path, etc.), there's a specific conflict when adding ACME challenge routes to a port that is already in use by other routes.
+### Overview
+Add support for custom socket handler functions with the simplest possible API - just pass a function that receives the socket.
 
-This results in the error: `Port 80 is already in use for ACME challenges` when SmartProxy tries to bind the ACME challenge route to a port that it's already using.
+### User Experience Goal
+```typescript
+const proxy = new SmartProxy({
+  routes: [{
+    name: 'my-custom-protocol',
+    match: { ports: 9000, domains: 'custom.example.com' },
+    action: {
+      type: 'socket-handler',
+      socketHandler: (socket) => {
+        // User has full control of the socket
+        socket.write('Welcome!\n');
+        socket.on('data', (data) => {
+          socket.write(`Echo: ${data}`);
+        });
+      }
+    }
+  }]
+});
+```
 
-### Root Cause Analysis
-1. **Double Binding Attempt**: SmartProxy tries to bind to port 80 twice - once for application routes and once for ACME challenge routes.
-2. **Overlapping Route Updates**: When adding a challenge route, it triggers a port binding operation without checking if the port is already bound.
-3. **Naive Error Handling**: The code detects EADDRINUSE but doesn't distinguish between external conflicts and internal conflicts.
-4. **Port Binding Semantics**: The port manager doesn't recognize that a port already bound by SmartProxy can be reused for additional routes.
+That's it. Simple and powerful.
 
-### Solution Architecture
-We need a more intelligent approach to port binding that understands when a port can be shared between routes vs. when a new binding is needed:
+---
 
-1. **Port Binding Awareness**: Track what ports are already bound by SmartProxy itself.
-2. **Smart Route Updates**: Only attempt to bind to ports that aren't already bound by SmartProxy.
-3. **Route Merging Logic**: When adding ACME challenge routes, merge them with existing routes on the same ports.
-4. **Dynamic Port Management**: Release port bindings when no routes are using them and rebind when needed.
-5. **Improved Error Recovery**: Handle port conflicts gracefully, with distinct handling for internal vs. external conflicts.
+## Phase 1: Minimal Type Changes
 
-### Implementation Plan
+### 1.1 Add Socket Handler Action Type
+**File:** `ts/proxies/smart-proxy/models/route-types.ts`
 
-#### Phase 1: Improve Port Manager Intelligence
-- [x] Enhance `PortManager` to distinguish between ports that need new bindings vs ports that can reuse existing bindings
-- [x] Add an internal tracking mechanism to detect when a requested port is already bound internally
-- [x] Modify port addition logic to skip binding operations for ports already bound by SmartProxy
-- [x] Implement reference counting for port bindings to track how many routes use each port
-- [x] Add logic to release port bindings when no routes are using them anymore
-- [x] Update error handling to provide more context for port binding failures
+```typescript
+// Update action type
+export type TRouteActionType = 'forward' | 'redirect' | 'block' | 'static' | 'socket-handler';
 
-#### Phase 2: Refine ACME Challenge Route Integration
-- [x] Modify `addChallengeRoute()` to check if the port is already in use by SmartProxy
-- [x] Ensure route updates don't trigger unnecessary port binding operations
-- [x] Implement a merging strategy for ACME routes with existing routes on the same port
-- [x] Add diagnostic logging to track route and port binding relationships
+// Add simple socket handler type
+export type TSocketHandler = (socket: net.Socket) => void | Promise<void>;
 
-#### Phase 3: Enhance Proxy Route Management
-- [x] Restructure route update process to group routes by port
-- [x] Implement a more efficient route update mechanism that minimizes port binding operations
-- [x] Develop port lifecycle management to track usage across route changes
-- [x] Add validation to detect potential binding conflicts before attempting operations
-- [ ] Create a proper route dependency graph to understand the relationships between routes
-- [x] Implement efficient detection of "orphaned" ports that no longer have associated routes
+// Extend IRouteAction
+export interface IRouteAction {
+  // ... existing properties
+  
+  // Socket handler function (when type is 'socket-handler')
+  socketHandler?: TSocketHandler;
+}
+```
 
-#### Phase 4: Improve Error Handling and Recovery
-- [x] Enhance error messages to be more specific about the nature of port conflicts
-- [x] Add recovery mechanisms for common port binding scenarios
-- [ ] Implement a fallback port selection strategy for ACME challenges
-- [x] Create a more robust validation system to catch issues before they cause runtime errors
+---
 
-### Detailed Technical Tasks
+## Phase 2: Simple Implementation
 
-#### Phase 1: Improve Port Manager Intelligence
-1. Modify `/ts/proxies/smart-proxy/port-manager.ts`:
-   - Add a new method `isPortBoundBySmartProxy(port: number): boolean`
-   - Refactor `addPort()` to check if the port is already bound
-   - Update `updatePorts()` to be more intelligent about which ports need binding
-   - Add reference counting for port usage
+### 2.1 Update Route Connection Handler
+**File:** `ts/proxies/smart-proxy/route-connection-handler.ts`
 
-2. Implement Port Reference Counting:
-   ```typescript
-   // Add to PortManager class
-   private portRefCounts: Map<number, number> = new Map();
-   
-   public incrementPortRefCount(port: number): void {
-     const currentCount = this.portRefCounts.get(port) || 0;
-     this.portRefCounts.set(port, currentCount + 1);
-     logger.log('debug', `Port ${port} reference count increased to ${currentCount + 1}`, { port, refCount: currentCount + 1 });
-   }
-   
-   public decrementPortRefCount(port: number): number {
-     const currentCount = this.portRefCounts.get(port) || 0;
-     if (currentCount <= 0) {
-       logger.log('warn', `Attempted to decrement reference count for port ${port} below zero`, { port });
-       return 0;
-     }
-     
-     const newCount = currentCount - 1;
-     this.portRefCounts.set(port, newCount);
-     logger.log('debug', `Port ${port} reference count decreased to ${newCount}`, { port, refCount: newCount });
-     return newCount;
-   }
-   
-   public getPortRefCount(port: number): number {
-     return this.portRefCounts.get(port) || 0;
-   }
-   ```
+In the `handleConnection` method, add handling for socket-handler:
 
-3. Port Binding Logic Enhancements:
-   ```typescript
-   public async addPort(port: number): Promise<void> {
-     // If already bound by this instance, just increment ref count and return
-     if (this.servers.has(port)) {
-       this.incrementPortRefCount(port);
-       logger.log('debug', `Port ${port} is already bound by SmartProxy, reusing binding`, { port });
-       return;
-     }
-     
-     // Initialize ref count for new port
-     this.portRefCounts.set(port, 1);
-     
-     // Continue with normal binding...
-   }
-   
-   public async removePort(port: number): Promise<void> {
-     // Decrement reference count
-     const newCount = this.decrementPortRefCount(port);
-     
-     // If port is still in use by other routes, keep it
-     if (newCount > 0) {
-       logger.log('debug', `Port ${port} still in use by ${newCount} routes, keeping binding open`, { port, refCount: newCount });
-       return;
-     }
-     
-     // No more references, can actually close the port
-     const server = this.servers.get(port);
-     if (!server) {
-       logger.log('warn', `Port ${port} not found in servers map`, { port });
-       return;
-     }
-     
-     // Continue with normal unbinding logic...
-   }
-   ```
+```typescript
+// After route matching...
+if (matchedRoute) {
+  const action = matchedRoute.action;
+  
+  if (action.type === 'socket-handler') {
+    if (!action.socketHandler) {
+      logger.error('socket-handler action missing socketHandler function');
+      socket.destroy();
+      return;
+    }
+    
+    try {
+      // Simply call the handler with the socket
+      const result = action.socketHandler(socket);
+      
+      // If it returns a promise, handle errors
+      if (result instanceof Promise) {
+        result.catch(error => {
+          logger.error('Socket handler error:', error);
+          if (!socket.destroyed) {
+            socket.destroy();
+          }
+        });
+      }
+    } catch (error) {
+      logger.error('Socket handler error:', error);
+      if (!socket.destroyed) {
+        socket.destroy();
+      }
+    }
+    
+    return; // Done - user has control now
+  }
+  
+  // ... rest of existing action handling
+}
+```
 
-4. Add Smarter Port Conflict Detection:
-   ```typescript
-   private isPortConflict(error: any): { isConflict: boolean; isExternal: boolean } {
-     if (error.code !== 'EADDRINUSE') {
-       return { isConflict: false, isExternal: false };
-     }
-     
-     // Check if we already have this port
-     const isBoundInternally = this.servers.has(Number(error.port));
-     return { isConflict: true, isExternal: !isBoundInternally };
-   }
-   ```
+---
 
-#### Phase 2: Refine ACME Challenge Route Integration
-1. Modify `/ts/proxies/smart-proxy/certificate-manager.ts`:
-   - Enhance `addChallengeRoute()` to be aware of existing port bindings
-   - Add port verification before attempting to add challenge routes
+## Phase 3: Optional Context (If Needed)
 
-2. Smart Route Merging Logic:
-   ```typescript
-   private async addChallengeRoute(): Promise<void> {
-     // Check if route is already active
-     if (this.challengeRouteActive) {
-       return;
-     }
+If users need more info, we can optionally pass a minimal context as a second parameter:
 
-     // Create challenge route
-     const challengeRoute = this.challengeRoute;
-     const challengePort = this.globalAcmeDefaults?.port || 80;
-     
-     // Check if port is already in use by another route
-     const portAlreadyUsed = this.routes.some(r => 
-       Array.isArray(r.match.ports) 
-       ? r.match.ports.includes(challengePort)
-       : r.match.ports === challengePort
-     );
-     
-     if (portAlreadyUsed) {
-       logger.log('info', `Port ${challengePort} is already used by an existing route, merging ACME challenge route`);
-     }
-     
-     // Continue with route update...
-   }
-   ```
+```typescript
+export type TSocketHandler = (
+  socket: net.Socket, 
+  context?: {
+    route: IRouteConfig;
+    clientIp: string;
+    localPort: number;
+  }
+) => void | Promise<void>;
+```
 
-3. Update Route Manager Communication:
-   ```typescript
-   // Add this method to smart-proxy.ts
-   private async addRouteWithoutRebinding(route: IRouteConfig): Promise<void> {
-     // Add route to configuration without triggering a port rebind
-     this.settings.routes.push(route);
-     this.routeManager.updateRoutes(this.settings.routes);
-     
-     // Update HttpProxy if needed, but skip port binding updates
-     if (this.httpProxyBridge.getHttpProxy()) {
-       await this.httpProxyBridge.syncRoutesToHttpProxy(this.settings.routes);
-     }
-   }
-   ```
+Usage:
+```typescript
+socketHandler: (socket, context) => {
+  console.log(`Connection from ${context.clientIp} to port ${context.localPort}`);
+  // Handle socket...
+}
+```
 
-#### Phase 3: Enhance Proxy Route Management
-1. Modify `/ts/proxies/smart-proxy/smart-proxy.ts`:
-   - Refactor `updateRoutes()` to group routes by port
-   - Implement incremental updates that preserve port bindings
-   - Add orphaned port detection and cleanup
+---
 
-2. Group Routes by Port:
-   ```typescript
-   private groupRoutesByPort(routes: IRouteConfig[]): Map<number, IRouteConfig[]> {
-     const portMap = new Map<number, IRouteConfig[]>();
-     
-     for (const route of routes) {
-       const ports = Array.isArray(route.match.ports) 
-         ? route.match.ports 
-         : [route.match.ports];
-         
-       for (const port of ports) {
-         if (!portMap.has(port)) {
-           portMap.set(port, []);
-         }
-         portMap.get(port)!.push(route);
-       }
-     }
-     
-     return portMap;
-   }
-   ```
+## Phase 4: Helper Utilities (Optional)
 
-3. Implement Port Usage Tracking:
-   ```typescript
-   private updatePortUsageMap(routes: IRouteConfig[]): Map<number, Set<string>> {
-     // Map of port -> Set of route names using that port
-     const portUsage = new Map<number, Set<string>>();
-     
-     for (const route of routes) {
-       const ports = Array.isArray(route.match.ports) 
-         ? route.match.ports 
-         : [route.match.ports];
-         
-       const routeName = route.name || `unnamed_${Math.random().toString(36).substring(2, 9)}`;
-       
-       for (const port of ports) {
-         if (!portUsage.has(port)) {
-           portUsage.set(port, new Set());
-         }
-         portUsage.get(port)!.add(routeName);
-       }
-     }
-     
-     return portUsage;
-   }
-   
-   private findOrphanedPorts(oldUsage: Map<number, Set<string>>, newUsage: Map<number, Set<string>>): number[] {
-     // Find ports that have no routes in new configuration
-     const orphanedPorts: number[] = [];
-     
-     for (const [port, routes] of oldUsage.entries()) {
-       if (!newUsage.has(port) || newUsage.get(port)!.size === 0) {
-         orphanedPorts.push(port);
-         logger.log('info', `Port ${port} no longer has any associated routes, will be released`, { port });
-       }
-     }
-     
-     return orphanedPorts;
-   }
-   ```
+### 4.1 Common Patterns
+**File:** `ts/proxies/smart-proxy/utils/route-helpers.ts`
 
-4. Implement Incremental Update Logic:
-   ```typescript
-   public async updateRoutesIncremental(newRoutes: IRouteConfig[]): Promise<void> {
-     // Track port usage before and after update
-     const oldPortUsage = this.updatePortUsageMap(this.settings.routes);
-     const newPortUsage = this.updatePortUsageMap(newRoutes);
-     
-     // Find orphaned ports - ports that no longer have any routes
-     const orphanedPorts = this.findOrphanedPorts(oldPortUsage, newPortUsage);
-     
-     // Ports that need new bindings - not in old configuration
-     const newBindingPorts = [...newPortUsage.keys()].filter(p => !oldPortUsage.has(p));
-     
-     // Close orphaned ports
-     if (orphanedPorts.length > 0) {
-       logger.log('info', `Releasing ${orphanedPorts.length} orphaned ports: ${orphanedPorts.join(', ')}`, { ports: orphanedPorts });
-       await this.portManager.removePorts(orphanedPorts);
-     }
-     
-     // Bind to new ports
-     if (newBindingPorts.length > 0) {
-       logger.log('info', `Binding to ${newBindingPorts.length} new ports: ${newBindingPorts.join(', ')}`, { ports: newBindingPorts });
-       await this.portManager.addPorts(newBindingPorts);
-     }
-     
-     // Update route configuration
-     this.settings.routes = newRoutes;
-     this.routeManager.updateRoutes(newRoutes);
-     
-     // Update other components...
-   }
-   ```
+```typescript
+// Simple helper to create socket handler routes
+export function createSocketHandlerRoute(
+  domains: string | string[],
+  ports: TPortRange,
+  handler: TSocketHandler,
+  options?: { name?: string; priority?: number }
+): IRouteConfig {
+  return {
+    name: options?.name || 'socket-handler-route',
+    priority: options?.priority || 50,
+    match: { domains, ports },
+    action: {
+      type: 'socket-handler',
+      socketHandler: handler
+    }
+  };
+}
 
-#### Phase 4: Improve Error Handling and Recovery
-1. Enhance Error Reporting:
-   ```typescript
-   private handlePortBindingError(port: number, error: any): void {
-     if (error.code === 'EADDRINUSE') {
-       const isInternalConflict = this.portManager.isPortBoundBySmartProxy(port);
-       if (isInternalConflict) {
-         logger.log('warn', `Port ${port} is already bound by SmartProxy. This is likely a route configuration issue.`, { port });
-       } else {
-         logger.log('error', `Port ${port} is in use by another application. Please choose a different port.`, { port });
-       }
-     } else {
-       logger.log('error', `Failed to bind to port ${port}: ${error.message}`, { port, error });
-     }
-   }
-   ```
+// Pre-built handlers for common cases
+export const SocketHandlers = {
+  // Simple echo server
+  echo: (socket: net.Socket) => {
+    socket.on('data', data => socket.write(data));
+  },
+  
+  // TCP proxy
+  proxy: (targetHost: string, targetPort: number) => (socket: net.Socket) => {
+    const target = net.connect(targetPort, targetHost);
+    socket.pipe(target);
+    target.pipe(socket);
+    socket.on('close', () => target.destroy());
+    target.on('close', () => socket.destroy());
+  },
+  
+  // Line-based protocol
+  lineProtocol: (handler: (line: string, socket: net.Socket) => void) => (socket: net.Socket) => {
+    let buffer = '';
+    socket.on('data', (data) => {
+      buffer += data.toString();
+      const lines = buffer.split('\n');
+      buffer = lines.pop() || '';
+      lines.forEach(line => handler(line, socket));
+    });
+  }
+};
+```
 
-2. Implement ACME Port Fallback Strategy:
-   ```typescript
-   private async selectAcmePort(): Promise<number> {
-     const preferredPort = this.globalAcmeDefaults?.port || 80;
-     
-     // Check if preferred port is already bound internally
-     if (this.portManager.isPortBoundBySmartProxy(preferredPort)) {
-       // We can use it without a new binding
-       return preferredPort;
-     }
-     
-     // Try to bind to preferred port
-     try {
-       // Temporary test binding
-       const server = plugins.net.createServer();
-       await new Promise<void>((resolve, reject) => {
-         server.listen(preferredPort, () => {
-           server.close();
-           resolve();
-         }).on('error', reject);
-       });
-       
-       // If we get here, port is available
-       return preferredPort;
-     } catch (error) {
-       if (error.code === 'EADDRINUSE') {
-         // Port is unavailable, try fallback ports
-         for (const fallbackPort of [8080, 8081, 8082, 8083, 8084]) {
-           try {
-             // Test if we can bind to fallback
-             const server = plugins.net.createServer();
-             await new Promise<void>((resolve, reject) => {
-               server.listen(fallbackPort, () => {
-                 server.close();
-                 resolve();
-               }).on('error', reject);
-             });
-             
-             logger.log('warn', `Primary ACME port ${preferredPort} is unavailable, using fallback port ${fallbackPort}`);
-             return fallbackPort;
-           } catch {
-             // Try next fallback
-           }
-         }
-       }
-       
-       // All attempts failed
-       throw new Error(`Could not find an available port for ACME challenges`);
-     }
-   }
-   ```
+---
 
-### Testing Strategy
-1. **Unit Tests**:
-   - Test port binding intelligence
-   - Test route merging logic
-   - Test error handling mechanisms
-   - Test port reference counting
-   - Test orphaned port detection and cleanup
+## Usage Examples
 
-2. **Integration Tests**:
-   - Test multiple routes on the same port
-   - Test ACME challenges on ports with existing routes
-   - Test dynamic route addition and removal
-   - Test port lifecycle (bind → share → release)
-   - Test various recovery scenarios
+### Example 1: Custom Protocol
+```typescript
+{
+  name: 'custom-protocol',
+  match: { ports: 9000 },
+  action: {
+    type: 'socket-handler',
+    socketHandler: (socket) => {
+      socket.write('READY\n');
+      socket.on('data', (data) => {
+        const cmd = data.toString().trim();
+        if (cmd === 'PING') socket.write('PONG\n');
+        else if (cmd === 'QUIT') socket.end();
+        else socket.write('ERROR: Unknown command\n');
+      });
+    }
+  }
+}
+```
 
-3. **Stress Tests**:
-   - Test rapid route updates
-   - Test concurrent operations
-   - Test large scale route changes (add/remove many at once)
-   - Test frequent changes to see if ports are properly released
-   - Test recovery from port conflicts
+### Example 2: Simple TCP Proxy
+```typescript
+{
+  name: 'tcp-proxy',
+  match: { ports: 8080, domains: 'proxy.example.com' },
+  action: {
+    type: 'socket-handler',
+    socketHandler: SocketHandlers.proxy('backend.local', 3000)
+  }
+}
+```
 
-### Release Plan
-1. **19.4.0** - Phase 1 & 2: Port Manager and ACME Route Improvements
-2. **19.5.0** - Phase 3: Enhanced Route Management
-3. **19.6.0** - Phase 4: Improved Error Handling and Recovery
+### Example 3: WebSocket with Custom Auth
+```typescript
+{
+  name: 'custom-websocket',
+  match: { ports: [80, 443], path: '/ws' },
+  action: {
+    type: 'socket-handler',
+    socketHandler: async (socket) => {
+      // Read HTTP headers
+      const headers = await readHttpHeaders(socket);
+      
+      // Custom auth check
+      if (!headers.authorization || !validateToken(headers.authorization)) {
+        socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
+        socket.end();
+        return;
+      }
+      
+      // Proceed with WebSocket upgrade
+      const ws = new WebSocket(socket, headers);
+      // ... handle WebSocket
+    }
+  }
+}
+```
+
+---
+
+## Benefits of This Approach
+
+1. **Dead Simple API**: Just pass a function that gets the socket
+2. **No New Classes**: No ForwardingHandler subclass needed
+3. **Minimal Changes**: Only touches type definitions and one handler method
+4. **Full Power**: Users have complete control over the socket
+5. **Backward Compatible**: No changes to existing functionality
+6. **Easy to Test**: Just test the socket handler functions directly
+
+---
+
+## Implementation Steps
+
+1. Add `'socket-handler'` to `TRouteActionType` (5 minutes)
+2. Add `socketHandler?: TSocketHandler` to `IRouteAction` (5 minutes)
+3. Add socket-handler case in `RouteConnectionHandler.handleConnection()` (15 minutes)
+4. Add helper functions (optional, 30 minutes)
+5. Write tests (2 hours)
+6. Update documentation (1 hour)
+
+**Total implementation time: ~4 hours** (vs 6 weeks for the complex version)
+
+---
+
+## What We're NOT Doing
+
+- ❌ Creating new ForwardingHandler classes
+- ❌ Complex context objects with utils
+- ❌ HTTP request handling for socket handlers
+- ❌ Complex protocol detection mechanisms
+- ❌ Middleware patterns
+- ❌ Lifecycle hooks
+
+Keep it simple. The user just wants to handle a socket.
+
+---
+
+## Success Criteria
+
+- ✅ Users can define a route with `type: 'socket-handler'`
+- ✅ Users can provide a function that receives the socket
+- ✅ The function is called when a connection matches the route
+- ✅ Error handling prevents crashes
+- ✅ No performance impact on existing routes
+- ✅ Clean, simple API that's easy to understand
+
+---
+
+## Implementation Notes (Completed)
+
+### What Was Implemented
+1. **Type Definitions** - Added 'socket-handler' to TRouteActionType and TSocketHandler type
+2. **Route Handler** - Added socket-handler case in RouteConnectionHandler switch statement  
+3. **Error Handling** - Both sync and async errors are caught and logged
+4. **Initial Data Handling** - Initial chunks are re-emitted to handler's listeners
+5. **Helper Functions** - Added createSocketHandlerRoute and pre-built handlers (echo, proxy, etc.)
+6. **Full Test Coverage** - All test cases pass including async handlers and error handling
+
+### Key Implementation Details
+- Socket handlers require initial data from client to trigger routing (not TLS handshake)
+- The handler receives the raw socket after route matching
+- Both sync and async handlers are supported  
+- Errors in handlers terminate the connection gracefully
+- Helper utilities provide common patterns (echo server, TCP proxy, line protocol)
+
+### Usage Notes
+- Clients must send initial data to trigger the handler (even just a newline)
+- The socket is passed directly to the handler function
+- Handler has complete control over the socket lifecycle
+- No special context object needed - keeps it simple
+
+**Total implementation time: ~3 hours**

readme.plan2.md

@@ -0,0 +1,764 @@
+# SmartProxy Simplification Plan: Unify Action Types
+
+## Summary
+Complete removal of 'redirect', 'block', and 'static' action types, leaving only 'forward' and 'socket-handler'. All old code will be deleted entirely - no migration paths or backwards compatibility. Socket handlers will be enhanced to receive IRouteContext as a second parameter.
+
+## Goal
+Create a dramatically simpler SmartProxy with only two action types, where everything is either proxied (forward) or handled by custom code (socket-handler).
+
+## Current State
+```typescript
+export type TRouteActionType = 'forward' | 'redirect' | 'block' | 'static' | 'socket-handler';
+export type TSocketHandler = (socket: plugins.net.Socket) => void | Promise<void>;
+```
+
+## Target State
+```typescript
+export type TRouteActionType = 'forward' | 'socket-handler';
+export type TSocketHandler = (socket: plugins.net.Socket, context: IRouteContext) => void | Promise<void>;
+```
+
+## Benefits
+1. **Simpler API** - Only two action types to understand
+2. **Unified handling** - Everything is either forwarding or custom socket handling
+3. **More flexible** - Socket handlers can do anything the old types did and more
+4. **Less code** - Remove specialized handlers and their dependencies
+5. **Context aware** - Socket handlers get access to route context (domain, port, clientIp, etc.)
+6. **Clean codebase** - No legacy code or migration paths
+
+---
+
+## Phase 1: Code to Remove
+
+### 1.1 Action Type Handlers
+- `RouteConnectionHandler.handleRedirectAction()`
+- `RouteConnectionHandler.handleBlockAction()`
+- `RouteConnectionHandler.handleStaticAction()`
+
+### 1.2 Handler Classes
+- `RedirectHandler` class (http-proxy/handlers/)
+- `StaticHandler` class (http-proxy/handlers/)
+
+### 1.3 Type Definitions
+- 'redirect', 'block', 'static' from TRouteActionType
+- IRouteRedirect interface
+- IRouteStatic interface
+- Related properties in IRouteAction
+
+### 1.4 Helper Functions
+- `createStaticFileRoute()`
+- Any other helpers that create redirect/block/static routes
+
+---
+
+## Phase 2: Create Predefined Socket Handlers
+
+### 2.1 Block Handler
+```typescript
+export const SocketHandlers = {
+  // ... existing handlers
+  
+  /**
+   * Block connection immediately
+   */
+  block: (message?: string) => (socket: plugins.net.Socket, context: IRouteContext) => {
+    // Can use context for logging or custom messages
+    const finalMessage = message || `Connection blocked from ${context.clientIp}`;
+    if (finalMessage) {
+      socket.write(finalMessage);
+    }
+    socket.end();
+  },
+  
+  /**
+   * HTTP block response
+   */
+  httpBlock: (statusCode: number = 403, message?: string) => (socket: plugins.net.Socket, context: IRouteContext) => {
+    // Can customize message based on context
+    const defaultMessage = `Access forbidden for ${context.domain || context.clientIp}`;
+    const finalMessage = message || defaultMessage;
+    
+    const response = [
+      `HTTP/1.1 ${statusCode} ${finalMessage}`,
+      'Content-Type: text/plain',
+      `Content-Length: ${finalMessage.length}`,
+      'Connection: close',
+      '',
+      finalMessage
+    ].join('\r\n');
+    
+    socket.write(response);
+    socket.end();
+  }
+};
+```
+
+### 2.2 Redirect Handler
+```typescript
+export const SocketHandlers = {
+  // ... existing handlers
+  
+  /**
+   * HTTP redirect handler
+   */
+  httpRedirect: (locationTemplate: string, statusCode: number = 301) => (socket: plugins.net.Socket, context: IRouteContext) => {
+    let buffer = '';
+    
+    socket.once('data', (data) => {
+      buffer += data.toString();
+      
+      // Parse HTTP request
+      const lines = buffer.split('\r\n');
+      const requestLine = lines[0];
+      const [method, path] = requestLine.split(' ');
+      
+      // Use domain from context (more reliable than Host header)
+      const domain = context.domain || 'localhost';
+      const port = context.port;
+      
+      // Replace placeholders in location using context
+      let finalLocation = locationTemplate
+        .replace('{domain}', domain)
+        .replace('{port}', String(port))
+        .replace('{path}', path)
+        .replace('{clientIp}', context.clientIp);
+      
+      const message = `Redirecting to ${finalLocation}`;
+      const response = [
+        `HTTP/1.1 ${statusCode} ${statusCode === 301 ? 'Moved Permanently' : 'Found'}`,
+        `Location: ${finalLocation}`,
+        'Content-Type: text/plain',
+        `Content-Length: ${message.length}`,
+        'Connection: close',
+        '',
+        message
+      ].join('\r\n');
+      
+      socket.write(response);
+      socket.end();
+    });
+  }
+};
+```
+
+### 2.3 Benefits of Context in Socket Handlers
+With routeContext as a second parameter, socket handlers can:
+- Access client IP for logging or rate limiting
+- Use domain information for multi-tenant handling
+- Check if connection is TLS and what version
+- Access route name/ID for metrics
+- Build more intelligent responses based on context
+
+Example advanced handler:
+```typescript
+const rateLimitHandler = (maxRequests: number) => {
+  const ipCounts = new Map<string, number>();
+  
+  return (socket: net.Socket, context: IRouteContext) => {
+    const count = (ipCounts.get(context.clientIp) || 0) + 1;
+    ipCounts.set(context.clientIp, count);
+    
+    if (count > maxRequests) {
+      socket.write(`Rate limit exceeded for ${context.clientIp}\n`);
+      socket.end();
+      return;
+    }
+    
+    // Process request...
+  };
+};
+```
+
+---
+
+## Phase 3: Update Helper Functions
+
+### 3.1 Update createHttpToHttpsRedirect
+```typescript
+export function createHttpToHttpsRedirect(
+  domains: string | string[],
+  httpsPort: number = 443,
+  options: Partial<IRouteConfig> = {}
+): IRouteConfig {
+  return {
+    name: options.name || `HTTP to HTTPS Redirect for ${Array.isArray(domains) ? domains.join(', ') : domains}`,
+    match: {
+      ports: options.match?.ports || 80,
+      domains
+    },
+    action: {
+      type: 'socket-handler',
+      socketHandler: SocketHandlers.httpRedirect(`https://{domain}:${httpsPort}{path}`, 301)
+    },
+    ...options
+  };
+}
+```
+
+### 3.2 Update createSocketHandlerRoute
+```typescript
+export function createSocketHandlerRoute(
+  domains: string | string[],
+  ports: TPortRange,
+  handler: TSocketHandler,
+  options: { name?: string; priority?: number; path?: string } = {}
+): IRouteConfig {
+  return {
+    name: options.name || 'socket-handler-route',
+    priority: options.priority !== undefined ? options.priority : 50,
+    match: {
+      domains,
+      ports,
+      ...(options.path && { path: options.path })
+    },
+    action: {
+      type: 'socket-handler',
+      socketHandler: handler
+    }
+  };
+}
+
+```
+
+---
+
+## Phase 4: Core Implementation Changes
+
+### 4.1 Update Route Connection Handler
+```typescript
+// Remove these methods:
+// - handleRedirectAction()
+// - handleBlockAction()  
+// - handleStaticAction()
+
+// Update switch statement to only have:
+switch (route.action.type) {
+  case 'forward':
+    return this.handleForwardAction(socket, record, route, initialChunk);
+    
+  case 'socket-handler':
+    this.handleSocketHandlerAction(socket, record, route, initialChunk);
+    return;
+    
+  default:
+    logger.log('error', `Unknown action type '${(route.action as any).type}'`);
+    socket.end();
+    this.connectionManager.cleanupConnection(record, 'unknown_action');
+}
+```
+
+### 4.2 Update Socket Handler to Pass Context
+```typescript
+private async handleSocketHandlerAction(
+  socket: plugins.net.Socket,
+  record: IConnectionRecord,
+  route: IRouteConfig,
+  initialChunk?: Buffer
+): Promise<void> {
+  const connectionId = record.id;
+  
+  // Create route context for the handler
+  const routeContext = this.createRouteContext({
+    connectionId: record.id,
+    port: record.localPort,
+    domain: record.lockedDomain,
+    clientIp: record.remoteIP,
+    serverIp: socket.localAddress || '',
+    isTls: record.isTLS || false,
+    tlsVersion: record.tlsVersion,
+    routeName: route.name,
+    routeId: route.id,
+  });
+  
+  try {
+    // Call the handler with socket AND context
+    const result = route.action.socketHandler(socket, routeContext);
+    
+    // Rest of implementation stays the same...
+  } catch (error) {
+    // Error handling...
+  }
+}
+```
+
+### 4.3 Clean Up Imports and Exports
+- Remove imports of deleted handler classes
+- Update index.ts files to remove exports
+- Clean up any unused imports
+
+---
+
+## Phase 5: Test Updates
+
+### 5.1 Remove Old Tests
+- Delete tests for redirect action type
+- Delete tests for block action type
+- Delete tests for static action type
+
+### 5.2 Add New Socket Handler Tests
+- Test block socket handler with context
+- Test HTTP redirect socket handler with context
+- Test that context is properly passed to all handlers
+
+---
+
+## Phase 6: Documentation Updates
+
+### 6.1 Update README.md
+- Remove documentation for redirect, block, static action types
+- Document the two remaining action types: forward and socket-handler
+- Add examples using socket handlers with context
+
+### 6.2 Update Type Documentation
+```typescript
+/**
+ * Route action types
+ * - 'forward': Proxy the connection to a target host:port
+ * - 'socket-handler': Pass the socket to a custom handler function
+ */
+export type TRouteActionType = 'forward' | 'socket-handler';
+
+/**
+ * Socket handler function
+ * @param socket - The incoming socket connection
+ * @param context - Route context with connection information
+ */
+export type TSocketHandler = (socket: net.Socket, context: IRouteContext) => void | Promise<void>;
+```
+
+### 6.3 Example Documentation
+```typescript
+// Example: Block connections from specific IPs
+const ipBlocker = (socket: net.Socket, context: IRouteContext) => {
+  if (context.clientIp.startsWith('192.168.')) {
+    socket.write('Internal IPs not allowed\n');
+    socket.end();
+    return;
+  }
+  // Forward to backend...
+};
+
+// Example: Domain-based routing
+const domainRouter = (socket: net.Socket, context: IRouteContext) => {
+  const backend = context.domain === 'api.example.com' ? 'api-server' : 'web-server';
+  // Forward to appropriate backend...
+};
+```
+
+---
+
+## Implementation Steps
+
+1. **Update TSocketHandler type** (15 minutes)
+   - Add IRouteContext as second parameter
+   - Update type definition in route-types.ts
+
+2. **Update socket handler implementation** (30 minutes)
+   - Create routeContext in handleSocketHandlerAction
+   - Pass context to socket handler function
+   - Update all existing socket handlers in route-helpers.ts
+
+3. **Remove old action types** (30 minutes)
+   - Remove 'redirect', 'block', 'static' from TRouteActionType
+   - Remove IRouteRedirect, IRouteStatic interfaces
+   - Clean up IRouteAction interface
+
+4. **Delete old handlers** (45 minutes)
+   - Delete handleRedirectAction, handleBlockAction, handleStaticAction methods
+   - Delete RedirectHandler and StaticHandler classes
+   - Remove imports and exports
+
+5. **Update route connection handler** (30 minutes)
+   - Simplify switch statement to only handle 'forward' and 'socket-handler'
+   - Remove all references to deleted action types
+
+6. **Create new socket handlers** (30 minutes)
+   - Implement SocketHandlers.block() with context
+   - Implement SocketHandlers.httpBlock() with context
+   - Implement SocketHandlers.httpRedirect() with context
+
+7. **Update helper functions** (30 minutes)
+   - Update createHttpToHttpsRedirect to use socket handler
+   - Delete createStaticFileRoute entirely
+   - Update any other affected helpers
+
+8. **Clean up tests** (1.5 hours)
+   - Delete all tests for removed action types
+   - Update socket handler tests to verify context parameter
+   - Add new tests for block/redirect socket handlers
+
+9. **Update documentation** (30 minutes)
+   - Update README.md
+   - Update type documentation
+   - Add examples of context usage
+
+**Total estimated time: ~5 hours**
+
+---
+
+## Considerations
+
+### Benefits
+- **Dramatically simpler API** - Only 2 action types instead of 5
+- **Consistent handling model** - Everything is either forwarding or custom handling
+- **More powerful** - Socket handlers with context can do much more than old static types
+- **Less code to maintain** - Removing hundreds of lines of specialized handler code
+- **Better extensibility** - Easy to add new socket handlers for any use case
+- **Context awareness** - All handlers get full connection context
+
+### Trade-offs
+- Static file serving removed (users should use nginx/apache behind proxy)
+- HTTP-specific logic (redirects) now in socket handlers (but more flexible)
+- Slightly more verbose configuration for simple blocks/redirects
+
+### Why This Approach
+1. **Simplicity wins** - Two concepts are easier to understand than five
+2. **Power through context** - Socket handlers with context are more capable
+3. **Clean break** - No migration paths means cleaner code
+4. **Future proof** - Easy to add new handlers without changing core
+
+---
+
+## Code Examples: Before and After
+
+### Block Action
+```typescript
+// BEFORE
+{
+  action: { type: 'block' }
+}
+
+// AFTER
+{
+  action: {
+    type: 'socket-handler',
+    socketHandler: SocketHandlers.block()
+  }
+}
+```
+
+### HTTP Redirect
+```typescript
+// BEFORE
+{
+  action: {
+    type: 'redirect',
+    redirect: {
+      to: 'https://{domain}:443{path}',
+      status: 301
+    }
+  }
+}
+
+// AFTER
+{
+  action: {
+    type: 'socket-handler',
+    socketHandler: SocketHandlers.httpRedirect('https://{domain}:443{path}', 301)
+  }
+}
+```
+
+### Custom Handler with Context
+```typescript
+// NEW CAPABILITY - Access to full context
+{
+  action: {
+    type: 'socket-handler',
+    socketHandler: (socket, context) => {
+      console.log(`Connection from ${context.clientIp} to ${context.domain}:${context.port}`);
+      // Custom handling based on context...
+    }
+  }
+}
+```
+
+---
+
+## Detailed Implementation Tasks
+
+### Step 1: Update TSocketHandler Type (15 minutes)
+- [ ] Open `ts/proxies/smart-proxy/models/route-types.ts`
+- [ ] Find line 14: `export type TSocketHandler = (socket: plugins.net.Socket) => void | Promise<void>;`
+- [ ] Import IRouteContext at top of file: `import type { IRouteContext } from '../../../core/models/route-context.js';`
+- [ ] Update TSocketHandler to: `export type TSocketHandler = (socket: plugins.net.Socket, context: IRouteContext) => void | Promise<void>;`
+- [ ] Save file
+
+### Step 2: Update Socket Handler Implementation (30 minutes)
+- [ ] Open `ts/proxies/smart-proxy/route-connection-handler.ts`
+- [ ] Find `handleSocketHandlerAction` method (around line 790)
+- [ ] Add route context creation after line 809:
+  ```typescript
+  // Create route context for the handler
+  const routeContext = this.createRouteContext({
+    connectionId: record.id,
+    port: record.localPort,
+    domain: record.lockedDomain,
+    clientIp: record.remoteIP,
+    serverIp: socket.localAddress || '',
+    isTls: record.isTLS || false,
+    tlsVersion: record.tlsVersion,
+    routeName: route.name,
+    routeId: route.id,
+  });
+  ```
+- [ ] Update line 812 from `const result = route.action.socketHandler(socket);`
+- [ ] To: `const result = route.action.socketHandler(socket, routeContext);`
+- [ ] Save file
+
+### Step 3: Update Existing Socket Handlers in route-helpers.ts (20 minutes)
+- [ ] Open `ts/proxies/smart-proxy/utils/route-helpers.ts`
+- [ ] Update `echo` handler (line 856):
+  - From: `echo: (socket: plugins.net.Socket) => {`
+  - To: `echo: (socket: plugins.net.Socket, context: IRouteContext) => {`
+- [ ] Update `proxy` handler (line 864):
+  - From: `proxy: (targetHost: string, targetPort: number) => (socket: plugins.net.Socket) => {`
+  - To: `proxy: (targetHost: string, targetPort: number) => (socket: plugins.net.Socket, context: IRouteContext) => {`
+- [ ] Update `lineProtocol` handler (line 879):
+  - From: `lineProtocol: (handler: (line: string, socket: plugins.net.Socket) => void) => (socket: plugins.net.Socket) => {`
+  - To: `lineProtocol: (handler: (line: string, socket: plugins.net.Socket) => void) => (socket: plugins.net.Socket, context: IRouteContext) => {`
+- [ ] Update `httpResponse` handler (line 896):
+  - From: `httpResponse: (statusCode: number, body: string) => (socket: plugins.net.Socket) => {`
+  - To: `httpResponse: (statusCode: number, body: string) => (socket: plugins.net.Socket, context: IRouteContext) => {`
+- [ ] Save file
+
+### Step 4: Remove Old Action Types from Type Definitions (15 minutes)
+- [ ] Open `ts/proxies/smart-proxy/models/route-types.ts`
+- [ ] Find line with TRouteActionType (around line 10)
+- [ ] Change from: `export type TRouteActionType = 'forward' | 'redirect' | 'block' | 'static' | 'socket-handler';`
+- [ ] To: `export type TRouteActionType = 'forward' | 'socket-handler';`
+- [ ] Find and delete IRouteRedirect interface (around line 123-126)
+- [ ] Find and delete IRouteStatic interface (if exists)
+- [ ] Find IRouteAction interface
+- [ ] Remove these properties:
+  - `redirect?: IRouteRedirect;`
+  - `static?: IRouteStatic;`
+- [ ] Save file
+
+### Step 5: Delete Handler Classes (15 minutes)
+- [ ] Delete file: `ts/proxies/http-proxy/handlers/redirect-handler.ts`
+- [ ] Delete file: `ts/proxies/http-proxy/handlers/static-handler.ts`
+- [ ] Open `ts/proxies/http-proxy/handlers/index.ts`
+- [ ] Delete all content (the file only exports RedirectHandler and StaticHandler)
+- [ ] Save empty file or delete it
+
+### Step 6: Remove Handler Methods from RouteConnectionHandler (30 minutes)
+- [ ] Open `ts/proxies/smart-proxy/route-connection-handler.ts`
+- [ ] Find and delete entire `handleRedirectAction` method (around line 723)
+- [ ] Find and delete entire `handleBlockAction` method (around line 750)
+- [ ] Find and delete entire `handleStaticAction` method (around line 773)
+- [ ] Remove imports at top:
+  - `import { RedirectHandler, StaticHandler } from '../http-proxy/handlers/index.js';`
+- [ ] Save file
+
+### Step 7: Update Switch Statement (15 minutes)
+- [ ] Still in `route-connection-handler.ts`
+- [ ] Find switch statement (around line 388)
+- [ ] Remove these cases:
+  - `case 'redirect': return this.handleRedirectAction(...)`
+  - `case 'block': return this.handleBlockAction(...)`
+  - `case 'static': this.handleStaticAction(...); return;`
+- [ ] Verify only 'forward' and 'socket-handler' cases remain
+- [ ] Save file
+
+### Step 8: Add New Socket Handlers to route-helpers.ts (30 minutes)
+- [ ] Open `ts/proxies/smart-proxy/utils/route-helpers.ts`
+- [ ] Add import at top: `import type { IRouteContext } from '../../../core/models/route-context.js';`
+- [ ] Add to SocketHandlers object:
+  ```typescript
+  /**
+   * Block connection immediately
+   */
+  block: (message?: string) => (socket: plugins.net.Socket, context: IRouteContext) => {
+    const finalMessage = message || `Connection blocked from ${context.clientIp}`;
+    if (finalMessage) {
+      socket.write(finalMessage);
+    }
+    socket.end();
+  },
+  
+  /**
+   * HTTP block response
+   */
+  httpBlock: (statusCode: number = 403, message?: string) => (socket: plugins.net.Socket, context: IRouteContext) => {
+    const defaultMessage = `Access forbidden for ${context.domain || context.clientIp}`;
+    const finalMessage = message || defaultMessage;
+    
+    const response = [
+      `HTTP/1.1 ${statusCode} ${finalMessage}`,
+      'Content-Type: text/plain',
+      `Content-Length: ${finalMessage.length}`,
+      'Connection: close',
+      '',
+      finalMessage
+    ].join('\r\n');
+    
+    socket.write(response);
+    socket.end();
+  },
+  
+  /**
+   * HTTP redirect handler
+   */
+  httpRedirect: (locationTemplate: string, statusCode: number = 301) => (socket: plugins.net.Socket, context: IRouteContext) => {
+    let buffer = '';
+    
+    socket.once('data', (data) => {
+      buffer += data.toString();
+      
+      const lines = buffer.split('\r\n');
+      const requestLine = lines[0];
+      const [method, path] = requestLine.split(' ');
+      
+      const domain = context.domain || 'localhost';
+      const port = context.port;
+      
+      let finalLocation = locationTemplate
+        .replace('{domain}', domain)
+        .replace('{port}', String(port))
+        .replace('{path}', path)
+        .replace('{clientIp}', context.clientIp);
+      
+      const message = `Redirecting to ${finalLocation}`;
+      const response = [
+        `HTTP/1.1 ${statusCode} ${statusCode === 301 ? 'Moved Permanently' : 'Found'}`,
+        `Location: ${finalLocation}`,
+        'Content-Type: text/plain',
+        `Content-Length: ${message.length}`,
+        'Connection: close',
+        '',
+        message
+      ].join('\r\n');
+      
+      socket.write(response);
+      socket.end();
+    });
+  }
+  ```
+- [ ] Save file
+
+### Step 9: Update Helper Functions (20 minutes)
+- [ ] Still in `route-helpers.ts`
+- [ ] Update `createHttpToHttpsRedirect` function (around line 109):
+  - Change the action to use socket handler:
+  ```typescript
+  action: {
+    type: 'socket-handler',
+    socketHandler: SocketHandlers.httpRedirect(`https://{domain}:${httpsPort}{path}`, 301)
+  }
+  ```
+- [ ] Delete entire `createStaticFileRoute` function (lines 277-322)
+- [ ] Save file
+
+### Step 10: Update Test Files (1.5 hours)
+#### 10.1 Update Socket Handler Tests
+- [ ] Open `test/test.socket-handler.ts`
+- [ ] Update all handler functions to accept context parameter
+- [ ] Open `test/test.socket-handler.simple.ts`
+- [ ] Update handler to accept context parameter
+- [ ] Open `test/test.socket-handler-race.ts`
+- [ ] Update handler to accept context parameter
+
+#### 10.2 Find and Update/Delete Redirect Tests
+- [ ] Search for files containing `type: 'redirect'` in test directory
+- [ ] For each file:
+  - [ ] If it's a redirect-specific test, delete the file
+  - [ ] If it's a mixed test, update redirect actions to use socket handlers
+- [ ] Files to check:
+  - [ ] `test/test.route-redirects.ts` - likely delete entire file
+  - [ ] `test/test.forwarding.ts` - update any redirect tests
+  - [ ] `test/test.forwarding.examples.ts` - update any redirect tests
+  - [ ] `test/test.route-config.ts` - update any redirect tests
+
+#### 10.3 Find and Update/Delete Block Tests  
+- [ ] Search for files containing `type: 'block'` in test directory
+- [ ] Update or delete as appropriate
+
+#### 10.4 Find and Delete Static Tests
+- [ ] Search for files containing `type: 'static'` in test directory
+- [ ] Delete static-specific test files
+- [ ] Remove static tests from mixed test files
+
+### Step 11: Clean Up Imports and Exports (20 minutes)
+- [ ] Open `ts/proxies/smart-proxy/utils/index.ts`
+- [ ] Ensure route-helpers.ts is exported
+- [ ] Remove any exports of deleted functions
+- [ ] Open `ts/index.ts`
+- [ ] Remove any exports of deleted types/interfaces
+- [ ] Search for any remaining imports of RedirectHandler or StaticHandler
+- [ ] Remove any found imports
+
+### Step 12: Documentation Updates (30 minutes)
+- [ ] Update README.md:
+  - [ ] Remove any mention of redirect, block, static action types
+  - [ ] Add examples of socket handlers with context
+  - [ ] Document the two action types: forward and socket-handler
+- [ ] Update any JSDoc comments in modified files
+- [ ] Add examples showing context usage
+
+### Step 13: Final Verification (15 minutes)
+- [ ] Run build: `pnpm build`
+- [ ] Fix any compilation errors
+- [ ] Run tests: `pnpm test`
+- [ ] Fix any failing tests
+- [ ] Search codebase for any remaining references to:
+  - [ ] 'redirect' action type
+  - [ ] 'block' action type
+  - [ ] 'static' action type
+  - [ ] RedirectHandler
+  - [ ] StaticHandler
+  - [ ] IRouteRedirect
+  - [ ] IRouteStatic
+
+### Step 14: Test New Functionality (30 minutes)
+- [ ] Create test for block socket handler with context
+- [ ] Create test for httpBlock socket handler with context
+- [ ] Create test for httpRedirect socket handler with context
+- [ ] Verify context is properly passed in all scenarios
+
+---
+
+## Files to be Modified/Deleted
+
+### Files to Modify:
+1. `ts/proxies/smart-proxy/models/route-types.ts` - Update types
+2. `ts/proxies/smart-proxy/route-connection-handler.ts` - Remove handlers, update switch
+3. `ts/proxies/smart-proxy/utils/route-helpers.ts` - Update handlers, add new ones
+4. `ts/proxies/http-proxy/handlers/index.ts` - Remove exports
+5. Various test files - Update to use socket handlers
+
+### Files to Delete:
+1. `ts/proxies/http-proxy/handlers/redirect-handler.ts`
+2. `ts/proxies/http-proxy/handlers/static-handler.ts`
+3. `test/test.route-redirects.ts` (likely)
+4. Any static-specific test files
+
+### Test Files Requiring Updates (15 files found):
+- test/test.acme-http01-challenge.ts
+- test/test.logger-error-handling.ts
+- test/test.port80-management.node.ts
+- test/test.route-update-callback.node.ts
+- test/test.acme-state-manager.node.ts
+- test/test.acme-route-creation.ts
+- test/test.forwarding.ts
+- test/test.route-redirects.ts
+- test/test.forwarding.examples.ts
+- test/test.acme-simple.ts
+- test/test.acme-http-challenge.ts
+- test/test.certificate-provisioning.ts
+- test/test.route-config.ts
+- test/test.route-utils.ts
+- test/test.certificate-simple.ts
+
+---
+
+## Success Criteria
+- ✅ Only 'forward' and 'socket-handler' action types remain
+- ✅ Socket handlers receive IRouteContext as second parameter
+- ✅ All old handler code completely removed
+- ✅ Redirect functionality works via context-aware socket handlers
+- ✅ Block functionality works via context-aware socket handlers  
+- ✅ All tests updated and passing
+- ✅ Documentation updated with new examples
+- ✅ No performance regression
+- ✅ Cleaner, simpler codebase

test/test.acme-http01-challenge.ts

@@ -10,7 +10,7 @@ tap.test('should correctly handle HTTP-01 challenge requests with initial data c
   const challengePath = `/.well-known/acme-challenge/${challengeToken}`;
   
   // Create a handler function that responds to ACME challenges
-  const acmeHandler = (context: any) => {
+  const acmeHandler = async (context: any) => {
     // Log request details for debugging
     console.log(`Received request: ${context.method} ${context.path}`);
     
@@ -46,7 +46,7 @@ tap.test('should correctly handle HTTP-01 challenge requests with initial data c
       name: 'acme-challenge-route',
       match: {
         ports: 8080,
-        paths: ['/.well-known/acme-challenge/*']
+        path: '/.well-known/acme-challenge/*'
       },
       action: {
         type: 'static',
@@ -99,7 +99,7 @@ tap.test('should correctly handle HTTP-01 challenge requests with initial data c
 // Test that non-existent challenge tokens return 404
 tap.test('should return 404 for non-existent challenge tokens', async (tapTest) => {
   // Create a handler function that behaves like a real ACME handler
-  const acmeHandler = (context: any) => {
+  const acmeHandler = async (context: any) => {
     if (context.path.startsWith('/.well-known/acme-challenge/')) {
       const token = context.path.substring('/.well-known/acme-challenge/'.length);
       // In this test, we only recognize one specific token
@@ -126,7 +126,7 @@ tap.test('should return 404 for non-existent challenge tokens', async (tapTest)
       name: 'acme-challenge-route',
       match: {
         ports: 8081,
-        paths: ['/.well-known/acme-challenge/*']
+        path: '/.well-known/acme-challenge/*'
       },
       action: {
         type: 'static',

test/test.acme-timing-simple.ts

@@ -37,6 +37,18 @@ tap.test('should defer certificate provisioning until ports are ready', async (t
     console.log('Creating mock cert manager');
     operationOrder.push('create-cert-manager');
     const mockCertManager = {
+      certStore: null,
+      smartAcme: null,
+      httpProxy: null,
+      renewalTimer: null,
+      pendingChallenges: new Map(),
+      challengeRoute: null,
+      certStatus: new Map(),
+      globalAcmeDefaults: null,
+      updateRoutesCallback: undefined,
+      challengeRouteActive: false,
+      isProvisioning: false,
+      acmeStateManager: null,
       initialize: async () => {
         operationOrder.push('cert-manager-init');
         console.log('Mock cert manager initialized');
@@ -56,8 +68,15 @@ tap.test('should defer certificate provisioning until ports are ready', async (t
       setAcmeStateManager: () => {},
       setUpdateRoutesCallback: () => {},
       getAcmeOptions: () => ({}),
-      getState: () => ({ challengeRouteActive: false })
-    };
+      getState: () => ({ challengeRouteActive: false }),
+      getCertStatus: () => new Map(),
+      checkAndRenewCertificates: async () => {},
+      addChallengeRoute: async () => {},
+      removeChallengeRoute: async () => {},
+      getCertificate: async () => null,
+      isValidCertificate: () => false,
+      waitForProvisioning: async () => {}
+    } as any;
     
     // Call initialize immediately as the real createCertificateManager does
     await mockCertManager.initialize();

test/test.connection-forwarding.ts

@@ -1,4 +1,4 @@
-import { expect, tap } from '@git.zone/tapbundle';
+import { expect, tap } from '@git.zone/tstest/tapbundle';
 import * as net from 'net';
 import * as tls from 'tls';
 import * as fs from 'fs';
@@ -61,7 +61,7 @@ tap.test('should forward TCP connections correctly', async () => {
         id: 'tcp-forward',
         name: 'TCP Forward Route',
         match: {
-          port: 8080,
+          ports: 8080,
         },
         action: {
           type: 'forward',
@@ -110,8 +110,8 @@ tap.test('should handle TLS passthrough correctly', async () => {
         id: 'tls-passthrough',
         name: 'TLS Passthrough Route',
         match: {
-          port: 8443,
-          domain: 'test.example.com',
+          ports: 8443,
+          domains: 'test.example.com',
         },
         action: {
           type: 'forward',
@@ -171,8 +171,8 @@ tap.test('should handle SNI-based forwarding', async () => {
         id: 'domain-a',
         name: 'Domain A Route',
         match: {
-          port: 8443,
-          domain: 'a.example.com',
+          ports: 8443,
+          domains: 'a.example.com',
         },
         action: {
           type: 'forward',
@@ -189,8 +189,8 @@ tap.test('should handle SNI-based forwarding', async () => {
         id: 'domain-b',
         name: 'Domain B Route',
         match: {
-          port: 8443,
-          domain: 'b.example.com',
+          ports: 8443,
+          domains: 'b.example.com',
         },
         action: {
           type: 'forward',

test/test.forwarding-fix-verification.ts

@@ -112,7 +112,7 @@ tap.test('NFTables forward route should not terminate connections', async () =>
   // Wait a bit to ensure connection isn't immediately closed
   await new Promise(resolve => setTimeout(resolve, 1000));
   
-  expect(connectionClosed).toBe(false);
+  expect(connectionClosed).toEqual(false);
   console.log('NFTables connection stayed open as expected');
   
   client.end();

test/test.forwarding-regression.ts

@@ -1,4 +1,4 @@
-import { expect, tap } from '@git.zone/tapbundle';
+import { expect, tap } from '@git.zone/tstest/tapbundle';
 import * as net from 'net';
 import { SmartProxy } from '../ts/proxies/smart-proxy/smart-proxy.js';
 
@@ -35,7 +35,7 @@ tap.test('forward connections should not be immediately closed', async (t) => {
         id: 'forward-test',
         name: 'Forward Test Route',
         match: {
-          port: 8080,
+          ports: 8080,
         },
         action: {
           type: 'forward',
@@ -80,9 +80,15 @@ tap.test('forward connections should not be immediately closed', async (t) => {
   });
 
   // Wait for the welcome message
-  await t.waitForExpect(() => {
-    return dataReceived;
-  }, 'Data should be received from the server', 2000);
+  let waitTime = 0;
+  while (!dataReceived && waitTime < 2000) {
+    await new Promise(resolve => setTimeout(resolve, 100));
+    waitTime += 100;
+  }
+  
+  if (!dataReceived) {
+    throw new Error('Data should be received from the server');
+  }
 
   // Verify we got the welcome message
   expect(welcomeMessage).toContain('Welcome from test server');
@@ -94,7 +100,7 @@ tap.test('forward connections should not be immediately closed', async (t) => {
   await new Promise(resolve => setTimeout(resolve, 100));
   
   // Connection should still be open
-  expect(connectionClosed).toBe(false);
+  expect(connectionClosed).toEqual(false);
   
   // Clean up
   client.end();

test/test.http-fix-unit.ts

@@ -43,7 +43,7 @@ tap.test('should forward non-TLS connections on HttpProxy ports', async (tapTest
   
   // Test the logic from handleForwardAction
   const route = mockSettings.routes[0];
-  const action = route.action;
+  const action = route.action as any;
   
   // Simulate the fixed logic
   if (!action.tls) {
@@ -101,7 +101,7 @@ tap.test('should use direct connection for non-HttpProxy ports', async (tapTest)
   };
   
   const route = mockSettings.routes[0];
-  const action = route.action;
+  const action = route.action as any;
   
   // Test the logic
   if (!action.tls) {
@@ -162,7 +162,7 @@ tap.test('should handle ACME HTTP-01 challenges on port 80 with HttpProxy', asyn
   };
   
   const route = mockSettings.routes[0];
-  const action = route.action;
+  const action = route.action as any;
   
   // Test the fix for ACME HTTP-01 challenges
   if (!action.tls) {

test/test.http-fix-verification.ts

@@ -1,6 +1,6 @@
 import { tap, expect } from '@git.zone/tstest/tapbundle';
 import { RouteConnectionHandler } from '../ts/proxies/smart-proxy/route-connection-handler.js';
-import { ISmartProxyOptions } from '../ts/proxies/smart-proxy/models/interfaces.js';
+import type { ISmartProxyOptions } from '../ts/proxies/smart-proxy/models/interfaces.js';
 import * as net from 'net';
 
 // Direct test of the fix in RouteConnectionHandler
@@ -68,9 +68,9 @@ tap.test('should detect and forward non-TLS connections on useHttpProxy ports',
   };
   
   // Test: Create a mock socket representing non-TLS connection on port 8080
-  const mockSocket = new net.Socket();
-  mockSocket.localPort = 8080;
-  mockSocket.remoteAddress = '127.0.0.1';
+  const mockSocket = Object.create(net.Socket.prototype) as net.Socket;
+  Object.defineProperty(mockSocket, 'localPort', { value: 8080, writable: false });
+  Object.defineProperty(mockSocket, 'remoteAddress', { value: '127.0.0.1', writable: false });
   
   // Simulate the handler processing the connection
   handler.handleConnection(mockSocket);
@@ -147,9 +147,9 @@ tap.test('should handle TLS connections normally', async (tapTest) => {
     mockRouteManager as any
   );
   
-  const mockSocket = new net.Socket();
-  mockSocket.localPort = 443;
-  mockSocket.remoteAddress = '127.0.0.1';
+  const mockSocket = Object.create(net.Socket.prototype) as net.Socket;
+  Object.defineProperty(mockSocket, 'localPort', { value: 443, writable: false });
+  Object.defineProperty(mockSocket, 'remoteAddress', { value: '127.0.0.1', writable: false });
   
   handler.handleConnection(mockSocket);
   

test/test.http-forwarding-fix.ts

@@ -8,9 +8,23 @@ tap.test('should detect and forward non-TLS connections on HttpProxy ports', asy
   let forwardedToHttpProxy = false;
   let connectionPath = '';
   
-  // Mock the HttpProxy forwarding
-  const originalForward = SmartProxy.prototype['httpProxyBridge'].prototype.forwardToHttpProxy;
-  SmartProxy.prototype['httpProxyBridge'].prototype.forwardToHttpProxy = function(...args: any[]) {
+  // Create a SmartProxy instance first
+  const proxy = new SmartProxy({
+    useHttpProxy: [8080],
+    httpProxyPort: 8844,
+    routes: [{
+      name: 'test-http-forward',
+      match: { ports: 8080 },
+      action: {
+        type: 'forward',
+        target: { host: 'localhost', port: 8181 }
+      }
+    }]
+  });
+  
+  // Mock the HttpProxy forwarding on the instance
+  const originalForward = (proxy as any).httpProxyBridge.forwardToHttpProxy;
+  (proxy as any).httpProxyBridge.forwardToHttpProxy = async function(...args: any[]) {
     forwardedToHttpProxy = true;
     connectionPath = 'httpproxy';
     console.log('Mock: Connection forwarded to HttpProxy');
@@ -18,22 +32,8 @@ tap.test('should detect and forward non-TLS connections on HttpProxy ports', asy
     args[1].end(); // socket.end()
   };
   
-  // Create a SmartProxy with useHttpProxy configured
-  const proxy = new SmartProxy({
-    useHttpProxy: [8080],
-    httpProxyPort: 8844,
-    enableDetailedLogging: true,
-    routes: [{
-      name: 'test-route',
-      match: {
-        ports: 8080
-      },
-      action: {
-        type: 'forward',
-        target: { host: 'localhost', port: 8181 }
-      }
-    }]
-  });
+  // Add detailed logging to the existing proxy instance
+  proxy.settings.enableDetailedLogging = true;
   
   // Override the HttpProxy initialization to avoid actual HttpProxy setup
   proxy['httpProxyBridge'].getHttpProxy = () => ({} as any);
@@ -65,7 +65,8 @@ tap.test('should detect and forward non-TLS connections on HttpProxy ports', asy
   await proxy.stop();
   
   // Restore original method
-  SmartProxy.prototype['httpProxyBridge'].prototype.forwardToHttpProxy = originalForward;
+  // Restore original method
+  (proxy as any).httpProxyBridge.forwardToHttpProxy = originalForward;
 });
 
 // Test that verifies the fix detects non-TLS connections

test/test.http-port8080-simple.ts

@@ -51,7 +51,7 @@ tap.test('should handle ACME challenges on port 8080 with improved port binding
   const tempCertDir = './temp-certs';
   
   try {
-    await plugins.smartfile.SmartFile.createDirectory(tempCertDir);
+    await plugins.smartfile.fs.ensureDir(tempCertDir);
   } catch (error) {
     // Directory may already exist, that's ok
   }
@@ -156,8 +156,10 @@ tap.test('should handle ACME challenges on port 8080 with improved port binding
     console.log('Port binding attempts:', portBindAttempts);
     
     // Check that we tried to bind to port 9009
-    expect(portBindAttempts.includes(9009)).toEqual(true, 'Should attempt to bind to port 9009');
-    expect(portBindAttempts.includes(9003)).toEqual(true, 'Should attempt to bind to port 9003');
+    // Should attempt to bind to port 9009
+    expect(portBindAttempts.includes(9009)).toEqual(true);
+    // Should attempt to bind to port 9003
+    expect(portBindAttempts.includes(9003)).toEqual(true);
     
     // Get actual bound ports
     const boundPorts = proxy.getListeningPorts();
@@ -165,10 +167,12 @@ tap.test('should handle ACME challenges on port 8080 with improved port binding
     
     // If port 9009 was available, we should be bound to it
     if (acmePortAvailable) {
-      expect(boundPorts.includes(9009)).toEqual(true, 'Should be bound to port 9009 if available');
+      // Should be bound to port 9009 if available
+      expect(boundPorts.includes(9009)).toEqual(true);
     }
     
-    expect(boundPorts.includes(9003)).toEqual(true, 'Should be bound to port 9003');
+    // Should be bound to port 9003
+    expect(boundPorts.includes(9003)).toEqual(true);
     
     // Test adding a new route on port 8080
     console.log('Testing route update with port reuse...');
@@ -186,7 +190,7 @@ tap.test('should handle ACME challenges on port 8080 with improved port binding
           path: '/additional'
         },
         action: {
-          type: 'forward',
+          type: 'forward' as const,
           target: { host: 'localhost', port: targetPort }
         }
       }
@@ -198,16 +202,19 @@ tap.test('should handle ACME challenges on port 8080 with improved port binding
     console.log('Port binding attempts after update:', portBindAttempts);
     
     // We should not try to rebind port 9009 since it's already bound
-    expect(portBindAttempts.includes(9009)).toEqual(false, 'Should not attempt to rebind port 9009');
+    // Should not attempt to rebind port 9009
+    expect(portBindAttempts.includes(9009)).toEqual(false);
     
     // We should still be listening on both ports
     const portsAfterUpdate = proxy.getListeningPorts();
     console.log('Bound ports after update:', portsAfterUpdate);
     
     if (acmePortAvailable) {
-      expect(portsAfterUpdate.includes(9009)).toEqual(true, 'Should still be bound to port 9009');
+      // Should still be bound to port 9009
+      expect(portsAfterUpdate.includes(9009)).toEqual(true);
     }
-    expect(portsAfterUpdate.includes(9003)).toEqual(true, 'Should still be bound to port 9003');
+    // Should still be bound to port 9003
+    expect(portsAfterUpdate.includes(9003)).toEqual(true);
     
     // The test is successful at this point - we've verified the port binding intelligence
     console.log('Port binding intelligence verified successfully!');
@@ -227,16 +234,8 @@ tap.test('should handle ACME challenges on port 8080 with improved port binding
     
     // Clean up temp directory
     try {
-      // Try different removal methods
-      if (typeof plugins.smartfile.fs.removeManySync === 'function') {
-        plugins.smartfile.fs.removeManySync([tempCertDir]);
-      } else if (typeof plugins.smartfile.fs.removeDirectory === 'function') {
-        await plugins.smartfile.fs.removeDirectory(tempCertDir);
-      } else if (typeof plugins.smartfile.removeDirectory === 'function') {
-        await plugins.smartfile.removeDirectory(tempCertDir);
-      } else {
-        console.log('Unable to find appropriate directory removal method');
-      }
+      // Remove temp directory
+      await plugins.smartfile.fs.remove(tempCertDir);
     } catch (error) {
       console.error('Failed to remove temp directory:', error);
     }

test/test.nftables-forwarding.ts

@@ -29,7 +29,7 @@ tap.test('NFTables forwarding should not terminate connections', async () => {
         id: 'nftables-test',
         name: 'NFTables Test Route',
         match: {
-          port: 8080,
+          ports: 8080,
         },
         action: {
           type: 'forward',
@@ -45,7 +45,7 @@ tap.test('NFTables forwarding should not terminate connections', async () => {
         id: 'regular-test',
         name: 'Regular Forward Route',
         match: {
-          port: 8081,
+          ports: 8081,
         },
         action: {
           type: 'forward',
@@ -83,7 +83,7 @@ tap.test('NFTables forwarding should not terminate connections', async () => {
     // Check connection after 100ms
     setTimeout(() => {
       // Connection should still be alive even if app doesn't handle it
-      expect(nftablesConnection.destroyed).toBe(false);
+      expect(nftablesConnection.destroyed).toEqual(false);
       nftablesConnection.end();
       resolve();
     }, 100);

test/test.route-callback-simple.ts

@@ -45,9 +45,9 @@ tap.test('should set update routes callback on certificate manager', async () =>
       setUpdateRoutesCallback: function(callback: any) {
         callbackSet = true;
       },
-      setHttpProxy: function() {},
-      setGlobalAcmeDefaults: function() {},
-      setAcmeStateManager: function() {},
+      setHttpProxy: function(proxy: any) {},
+      setGlobalAcmeDefaults: function(defaults: any) {},
+      setAcmeStateManager: function(manager: any) {},
       initialize: async function() {},
       provisionAllCertificates: async function() {},
       stop: async function() {},

test/test.route-update-logger-errors.ts

@@ -55,7 +55,8 @@ tap.test('should have error handling around logger calls in route update callbac
     expect(true).toEqual(true);
   } catch (error) {
     // This shouldn't happen if our error handling is working
-    expect(false).toEqual(true, 'Error handling failed in addChallengeRoute');
+    // Error handling failed in addChallengeRoute
+    expect(false).toEqual(true);
   }
   
   // Verify that we handle errors in removeChallengeRoute
@@ -69,7 +70,8 @@ tap.test('should have error handling around logger calls in route update callbac
     expect(true).toEqual(true);
   } catch (error) {
     // This shouldn't happen if our error handling is working
-    expect(false).toEqual(true, 'Error handling failed in removeChallengeRoute');
+    // Error handling failed in removeChallengeRoute
+    expect(false).toEqual(true);
   }
 });
 

test/test.socket-handler-race.ts

@@ -0,0 +1,83 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as net from 'net';
+import { SmartProxy } from '../ts/index.js';
+
+tap.test('should handle async handler that sets up listeners after delay', async () => {
+  const proxy = new SmartProxy({
+    routes: [{
+      name: 'delayed-setup-handler',
+      match: { ports: 7777 },
+      action: {
+        type: 'socket-handler',
+        socketHandler: async (socket) => {
+          // Simulate async work BEFORE setting up listeners
+          await new Promise(resolve => setTimeout(resolve, 50));
+          
+          // Now set up the listener - with the race condition, this would miss initial data
+          socket.on('data', (data) => {
+            const message = data.toString().trim();
+            socket.write(`RECEIVED: ${message}\n`);
+            if (message === 'close') {
+              socket.end();
+            }
+          });
+          
+          // Send ready message
+          socket.write('HANDLER READY\n');
+        }
+      }
+    }],
+    enableDetailedLogging: false
+  });
+  
+  await proxy.start();
+  
+  // Test connection
+  const client = new net.Socket();
+  let response = '';
+  
+  client.on('data', (data) => {
+    response += data.toString();
+  });
+  
+  await new Promise<void>((resolve, reject) => {
+    client.connect(7777, 'localhost', () => {
+      // Send initial data immediately - this tests the race condition
+      client.write('initial-message\n');
+      resolve();
+    });
+    client.on('error', reject);
+  });
+  
+  // Wait for handler setup and initial data processing
+  await new Promise(resolve => setTimeout(resolve, 150));
+  
+  // Send another message to verify handler is working
+  client.write('test-message\n');
+  
+  // Wait for response
+  await new Promise(resolve => setTimeout(resolve, 50));
+  
+  // Send close command
+  client.write('close\n');
+  
+  // Wait for connection to close
+  await new Promise(resolve => {
+    client.on('close', () => resolve(undefined));
+  });
+  
+  console.log('Response:', response);
+  
+  // Should have received the ready message
+  expect(response).toContain('HANDLER READY');
+  
+  // Should have received the initial message (this would fail with race condition)
+  expect(response).toContain('RECEIVED: initial-message');
+  
+  // Should have received the test message
+  expect(response).toContain('RECEIVED: test-message');
+  
+  await proxy.stop();
+});
+
+export default tap.start();

test/test.socket-handler.simple.ts

@@ -0,0 +1,59 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as net from 'net';
+import { SmartProxy } from '../ts/index.js';
+
+tap.test('simple socket handler test', async () => {
+  const proxy = new SmartProxy({
+    routes: [{
+      name: 'simple-handler',
+      match: { 
+        ports: 8888
+        // No domains restriction - will match all connections on this port
+      },
+      action: {
+        type: 'socket-handler',
+        socketHandler: (socket) => {
+          console.log('Handler called!');
+          socket.write('HELLO\n');
+          socket.end();
+        }
+      }
+    }],
+    enableDetailedLogging: true
+  });
+  
+  await proxy.start();
+  
+  // Test connection
+  const client = new net.Socket();
+  let response = '';
+  
+  client.on('data', (data) => {
+    response += data.toString();
+  });
+  
+  await new Promise<void>((resolve, reject) => {
+    client.connect(8888, 'localhost', () => {
+      console.log('Connected');
+      // Send some initial data to trigger the handler
+      client.write('test\n');
+      resolve();
+    });
+    client.on('error', reject);
+  });
+  
+  // Wait for response
+  await new Promise(resolve => {
+    client.on('close', () => {
+      console.log('Connection closed');
+      resolve(undefined);
+    });
+  });
+  
+  console.log('Got response:', response);
+  expect(response).toEqual('HELLO\n');
+  
+  await proxy.stop();
+});
+
+export default tap.start();

test/test.socket-handler.ts

@@ -0,0 +1,173 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as net from 'net';
+import { SmartProxy } from '../ts/index.js';
+import type { IRouteConfig } from '../ts/index.js';
+
+let proxy: SmartProxy;
+
+tap.test('setup socket handler test', async () => {
+  // Create a simple socket handler route
+  const routes: IRouteConfig[] = [{
+    name: 'echo-handler',
+    match: { 
+      ports: 9999
+      // No domains restriction - matches all connections
+    },
+    action: {
+      type: 'socket-handler',
+      socketHandler: (socket) => {
+        console.log('Socket handler called');
+        // Simple echo server
+        socket.write('ECHO SERVER\n');
+        socket.on('data', (data) => {
+          console.log('Socket handler received data:', data.toString());
+          socket.write(`ECHO: ${data}`);
+        });
+        socket.on('error', (err) => {
+          console.error('Socket error:', err);
+        });
+      }
+    }
+  }];
+  
+  proxy = new SmartProxy({
+    routes,
+    enableDetailedLogging: false
+  });
+  
+  await proxy.start();
+});
+
+tap.test('should handle socket with custom function', async () => {
+  const client = new net.Socket();
+  let response = '';
+  
+  await new Promise<void>((resolve, reject) => {
+    client.connect(9999, 'localhost', () => {
+      console.log('Client connected to proxy');
+      resolve();
+    });
+    
+    client.on('error', reject);
+  });
+  
+  // Collect data
+  client.on('data', (data) => {
+    console.log('Client received:', data.toString());
+    response += data.toString();
+  });
+  
+  // Wait a bit for connection to stabilize
+  await new Promise(resolve => setTimeout(resolve, 50));
+  
+  // Send test data
+  console.log('Sending test data...');
+  client.write('Hello World\n');
+  
+  // Wait for response
+  await new Promise(resolve => setTimeout(resolve, 200));
+  
+  console.log('Total response:', response);
+  expect(response).toContain('ECHO SERVER');
+  expect(response).toContain('ECHO: Hello World');
+  
+  client.destroy();
+});
+
+tap.test('should handle async socket handler', async () => {
+  // Update route with async handler
+  await proxy.updateRoutes([{
+    name: 'async-handler',
+    match: { ports: 9999 },
+    action: {
+      type: 'socket-handler',
+      socketHandler: async (socket) => {
+        // Set up data handler first
+        socket.on('data', async (data) => {
+          console.log('Async handler received:', data.toString());
+          // Simulate async processing
+          await new Promise(resolve => setTimeout(resolve, 10));
+          const processed = `PROCESSED: ${data.toString().trim().toUpperCase()}\n`;
+          console.log('Sending:', processed);
+          socket.write(processed);
+        });
+        
+        // Then simulate async operation
+        await new Promise(resolve => setTimeout(resolve, 10));
+        socket.write('ASYNC READY\n');
+      }
+    }
+  }]);
+  
+  const client = new net.Socket();
+  let response = '';
+  
+  // Collect data
+  client.on('data', (data) => {
+    response += data.toString();
+  });
+  
+  await new Promise<void>((resolve, reject) => {
+    client.connect(9999, 'localhost', () => {
+      // Send initial data to trigger the handler
+      client.write('test data\n');
+      resolve();
+    });
+    
+    client.on('error', reject);
+  });
+  
+  // Wait for async processing
+  await new Promise(resolve => setTimeout(resolve, 200));
+  
+  console.log('Final response:', response);
+  expect(response).toContain('ASYNC READY');
+  expect(response).toContain('PROCESSED: TEST DATA');
+  
+  client.destroy();
+});
+
+tap.test('should handle errors in socket handler', async () => {
+  // Update route with error-throwing handler
+  await proxy.updateRoutes([{
+    name: 'error-handler',
+    match: { ports: 9999 },
+    action: {
+      type: 'socket-handler',
+      socketHandler: (socket) => {
+        throw new Error('Handler error');
+      }
+    }
+  }]);
+  
+  const client = new net.Socket();
+  let connectionClosed = false;
+  
+  client.on('close', () => {
+    connectionClosed = true;
+  });
+  
+  await new Promise<void>((resolve, reject) => {
+    client.connect(9999, 'localhost', () => {
+      // Connection established - send data to trigger handler
+      client.write('trigger\n');
+      resolve();
+    });
+    
+    client.on('error', () => {
+      // Ignore client errors - we expect the connection to be closed
+    });
+  });
+  
+  // Wait a bit
+  await new Promise(resolve => setTimeout(resolve, 100));
+  
+  // Socket should be closed due to handler error
+  expect(connectionClosed).toEqual(true);
+});
+
+tap.test('cleanup', async () => {
+  await proxy.stop();
+});
+
+export default tap.start();

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartproxy',
-  version: '19.4.1',
+  version: '19.5.1',
   description: 'A powerful proxy package with unified route-based configuration for high traffic management. Features include SSL/TLS support, flexible routing patterns, WebSocket handling, advanced security options, and automatic ACME certificate management.'
 }

ts/proxies/smart-proxy/models/route-types.ts

@@ -6,7 +6,12 @@ import type { PortRange } from '../../../proxies/nftables-proxy/models/interface
 /**
  * Supported action types for route configurations
  */
-export type TRouteActionType = 'forward' | 'redirect' | 'block' | 'static';
+export type TRouteActionType = 'forward' | 'redirect' | 'block' | 'static' | 'socket-handler';
+
+/**
+ * Socket handler function type
+ */
+export type TSocketHandler = (socket: plugins.net.Socket) => void | Promise<void>;
 
 /**
  * TLS handling modes for route configurations
@@ -297,6 +302,9 @@ export interface IRouteAction {
 
   // Handler function for static routes
   handler?: (context: IRouteContext) => Promise<IStaticResponse>;
+  
+  // Socket handler function (when type is 'socket-handler')
+  socketHandler?: TSocketHandler;
 }
 
 /**

ts/proxies/smart-proxy/route-connection-handler.ts

@@ -399,6 +399,15 @@ export class RouteConnectionHandler {
         this.handleStaticAction(socket, record, route, initialChunk);
         return;
 
+      case 'socket-handler':
+        logger.log('info', `Handling socket-handler action for route ${route.name}`, {
+          connectionId,
+          routeName: route.name,
+          component: 'route-handler'
+        });
+        this.handleSocketHandlerAction(socket, record, route, initialChunk);
+        return;
+
       default:
         logger.log('error', `Unknown action type '${(route.action as any).type}' for connection ${connectionId}`, {
           connectionId,
@@ -776,6 +785,75 @@ export class RouteConnectionHandler {
     }, record, initialChunk);
   }
 
+  /**
+   * Handle a socket-handler action for a route
+   */
+  private async handleSocketHandlerAction(
+    socket: plugins.net.Socket,
+    record: IConnectionRecord,
+    route: IRouteConfig,
+    initialChunk?: Buffer
+  ): Promise<void> {
+    const connectionId = record.id;
+    
+    if (!route.action.socketHandler) {
+      logger.log('error', 'socket-handler action missing socketHandler function', {
+        connectionId,
+        routeName: route.name,
+        component: 'route-handler'
+      });
+      socket.destroy();
+      this.connectionManager.cleanupConnection(record, 'missing_handler');
+      return;
+    }
+    
+    try {
+      // Call the handler
+      const result = route.action.socketHandler(socket);
+      
+      // Handle async handlers properly
+      if (result instanceof Promise) {
+        result
+          .then(() => {
+            // Emit initial chunk after async handler completes
+            if (initialChunk && initialChunk.length > 0) {
+              socket.emit('data', initialChunk);
+            }
+          })
+          .catch(error => {
+            logger.log('error', 'Socket handler error', {
+              connectionId,
+              routeName: route.name,
+              error: error.message,
+              component: 'route-handler'
+            });
+            if (!socket.destroyed) {
+              socket.destroy();
+            }
+            this.connectionManager.cleanupConnection(record, 'handler_error');
+          });
+      } else {
+        // For sync handlers, emit on next tick
+        if (initialChunk && initialChunk.length > 0) {
+          process.nextTick(() => {
+            socket.emit('data', initialChunk);
+          });
+        }
+      }
+    } catch (error) {
+      logger.log('error', 'Socket handler error', {
+        connectionId,
+        routeName: route.name,
+        error: error.message,
+        component: 'route-handler'
+      });
+      if (!socket.destroyed) {
+        socket.destroy();
+      }
+      this.connectionManager.cleanupConnection(record, 'handler_error');
+    }
+  }
+
   /**
    * Setup improved error handling for the outgoing connection
    */

ts/proxies/smart-proxy/utils/route-helpers.ts

@@ -19,6 +19,7 @@
  * - NFTables routes (createNfTablesRoute, createNfTablesTerminateRoute)
  */
 
+import * as plugins from '../../../plugins.js';
 import type { IRouteConfig, IRouteMatch, IRouteAction, IRouteTarget, TPortRange, IRouteContext } from '../models/route-types.js';
 
 /**
@@ -810,4 +811,99 @@ export function createCompleteNfTablesHttpsServer(
   );
   
   return [httpsRoute, httpRedirectRoute];
-}
+}
+
+/**
+ * Create a socket handler route configuration
+ * @param domains Domain(s) to match
+ * @param ports Port(s) to listen on
+ * @param handler Socket handler function
+ * @param options Additional route options
+ * @returns Route configuration object
+ */
+export function createSocketHandlerRoute(
+  domains: string | string[],
+  ports: TPortRange,
+  handler: (socket: plugins.net.Socket) => void | Promise<void>,
+  options: {
+    name?: string;
+    priority?: number;
+    path?: string;
+  } = {}
+): IRouteConfig {
+  return {
+    name: options.name || 'socket-handler-route',
+    priority: options.priority !== undefined ? options.priority : 50,
+    match: {
+      domains,
+      ports,
+      ...(options.path && { path: options.path })
+    },
+    action: {
+      type: 'socket-handler',
+      socketHandler: handler
+    }
+  };
+}
+
+/**
+ * Pre-built socket handlers for common use cases
+ */
+export const SocketHandlers = {
+  /**
+   * Simple echo server handler
+   */
+  echo: (socket: plugins.net.Socket) => {
+    socket.write('ECHO SERVER READY\n');
+    socket.on('data', data => socket.write(data));
+  },
+  
+  /**
+   * TCP proxy handler
+   */
+  proxy: (targetHost: string, targetPort: number) => (socket: plugins.net.Socket) => {
+    const target = plugins.net.connect(targetPort, targetHost);
+    socket.pipe(target);
+    target.pipe(socket);
+    socket.on('close', () => target.destroy());
+    target.on('close', () => socket.destroy());
+    target.on('error', (err) => {
+      console.error('Proxy target error:', err);
+      socket.destroy();
+    });
+  },
+  
+  /**
+   * Line-based protocol handler
+   */
+  lineProtocol: (handler: (line: string, socket: plugins.net.Socket) => void) => (socket: plugins.net.Socket) => {
+    let buffer = '';
+    socket.on('data', (data) => {
+      buffer += data.toString();
+      const lines = buffer.split('\n');
+      buffer = lines.pop() || '';
+      lines.forEach(line => {
+        if (line.trim()) {
+          handler(line.trim(), socket);
+        }
+      });
+    });
+  },
+  
+  /**
+   * Simple HTTP response handler (for testing)
+   */
+  httpResponse: (statusCode: number, body: string) => (socket: plugins.net.Socket) => {
+    const response = [
+      `HTTP/1.1 ${statusCode} ${statusCode === 200 ? 'OK' : 'Error'}`,
+      'Content-Type: text/plain',
+      `Content-Length: ${body.length}`,
+      'Connection: close',
+      '',
+      body
+    ].join('\r\n');
+    
+    socket.write(response);
+    socket.end();
+  }
+};