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:

   // 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:

   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

Implementation Summary

The bug has been successfully fixed through the following steps:

1. Bug Fix Applied: Added the missing setUpdateRoutesCallback call in the updateRoutes method
2. Tests Created: Comprehensive test suite validates the fix and prevents regression
3. Documentation Updated: Added section on dynamic route updates to the certificate management guide
4. Code Refactored: Extracted certificate manager creation into a helper method for better maintainability

The fix ensures that when routes are dynamically updated, the certificate manager maintains its ability to update routes for ACME challenges, preventing the "No route update callback set" error.

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