smartproxy/readme.plan.md

# SmartProxy Development Plan

cat /home/philkunz/.claude/CLAUDE.md

## Critical Bug Fix: Missing Route Update Callback in updateRoutes Method

### Problem Statement
SmartProxy v19.2.2 has a bug where the ACME certificate manager loses its route update callback when routes are dynamically updated. This causes the error "No route update callback set" and prevents automatic certificate acquisition.

### Root Cause
When `updateRoutes()` creates a new SmartCertManager instance, it fails to set the route update callback that's required for ACME challenges. This callback is properly set in `initializeCertificateManager()` but is missing from the route update flow.

### Implementation Plan

#### Phase 1: Fix the Bug
1. **Update the updateRoutes method** in `/mnt/data/lossless/push.rocks/smartproxy/ts/proxies/smart-proxy/smart-proxy.ts`
   - [ ] Add the missing callback setup before initializing the new certificate manager
   - [ ] Ensure the callback is set after creating the new SmartCertManager instance

#### Phase 2: Create Tests
2. **Write comprehensive tests** for the route update functionality
   - [ ] Create test file: `test/test.route-update-callback.node.ts`
   - [ ] Test that callback is preserved when routes are updated
   - [ ] Test that ACME challenges work after route updates
   - [ ] Test edge cases (multiple updates, no cert manager, etc.)

#### Phase 3: Enhance Documentation
3. **Update documentation** to clarify the route update behavior
   - [ ] Add section to certificate-management.md about dynamic route updates
   - [ ] Document the callback requirement for ACME challenges
   - [ ] Include example of proper route update implementation

#### Phase 4: Prevent Future Regressions
4. **Refactor for better maintainability**
   - [ ] Consider extracting certificate manager setup to a shared method
   - [ ] Add code comments explaining the callback requirement
   - [ ] Consider making the callback setup more explicit in the API

### Technical Details

#### Specific Code Changes
1. In `updateRoutes()` method (around line 535), add:
   ```typescript
   // Set route update callback for ACME challenges
   this.certManager.setUpdateRoutesCallback(async (routes) => {
     await this.updateRoutes(routes);
   });
   ```

2. Consider refactoring the certificate manager setup into a helper method to avoid duplication:
   ```typescript
   private async setupCertificateManager(
     routes: IRouteConfig[], 
     certStore: string, 
     acmeOptions?: any
   ): Promise<SmartCertManager> {
     const certManager = new SmartCertManager(routes, certStore, acmeOptions);
     
     // Always set up the route update callback
     certManager.setUpdateRoutesCallback(async (routes) => {
       await this.updateRoutes(routes);
     });
     
     if (this.networkProxyBridge.getNetworkProxy()) {
       certManager.setNetworkProxy(this.networkProxyBridge.getNetworkProxy());
     }
     
     return certManager;
   }
   ```

### Success Criteria
- [ ] ACME certificate acquisition works after route updates
- [ ] No "No route update callback set" errors occur
- [ ] All tests pass
- [ ] Documentation clearly explains the behavior
- [ ] Code is more maintainable and less prone to regression

### Timeline
- Phase 1: Immediate fix (30 minutes)
- Phase 2: Test creation (1 hour)
- Phase 3: Documentation (30 minutes)
- Phase 4: Refactoring (1 hour)

Total estimated time: 3 hours

### Notes
- This is a critical bug that affects production use of SmartProxy
- The fix is straightforward but requires careful testing
- Consider backporting to v19.2.x branch if maintaining multiple versions