smartproxy/readme.plan.md

SmartProxy Complete Route-Based Implementation Plan

Project Goal

Complete the refactoring of SmartProxy to a pure route-based configuration approach by:

1. Removing all remaining domain-based configuration code with no backward compatibility
2. Updating internal components to work directly and exclusively with route configurations
3. Eliminating all conversion functions and domain-based interfaces
4. Cleaning up deprecated methods and interfaces completely
5. Focusing entirely on route-based helper functions for the best developer experience

Current Status

The primary refactoring to route-based configuration has been successfully completed:

• SmartProxy now works exclusively with route-based configurations in its public API
• All test files have been updated to use route-based configurations
• Documentation has been updated to explain the route-based approach
• Helper functions have been implemented for creating route configurations
• All features are working correctly with the new approach

However, there are still some internal components that use domain-based configuration for compatibility:

1. CertProvisioner converts route configs to domain configs internally
2. NetworkProxyBridge has conversion methods for domain-to-route configurations
3. Legacy interfaces and types still exist in the codebase
4. Some deprecated methods remain for backward compatibility

Implementation Checklist

Phase 1: Refactor CertProvisioner for Native Route Support

• 1.1 Update CertProvisioner constructor to store routeConfigs directly
• 1.2 Remove extractDomainsFromRoutes() method and domainConfigs array
• 1.3 Create extractCertificateRoutesFromRoutes() method to find routes needing certificates
• 1.4 Update provisionAllDomains() to work with route configurations
• 1.5 Update provisionDomain() to handle route configs
• 1.6 Modify renewal tracking to use routes instead of domains
• 1.7 Update renewals scheduling to use route-based approach
• 1.8 Refactor requestCertificate() method to use routes
• 1.9 Update ICertificateData interface to include route references
• 1.10 Update certificate event handling to include route information
• 1.11 Add unit tests for route-based certificate provisioning
• 1.12 Add tests for wildcard domain handling with routes
• 1.13 Test certificate renewal with route configurations
• 1.14 Update certificate-types.ts to remove domain-based types

Phase 2: Refactor NetworkProxyBridge for Direct Route Processing

• 2.1 Update NetworkProxyBridge constructor to work directly with routes
• 2.2 Refactor syncRoutesToNetworkProxy() to eliminate domain conversion
• 2.3 Remove convertRoutesToNetworkProxyConfigs() method
• 2.4 Remove syncDomainConfigsToNetworkProxy() method
• 2.5 Implement direct mapping from routes to NetworkProxy configs
• 2.6 Update handleCertificateEvent() to work with routes
• 2.7 Update applyExternalCertificate() to use route information
• 2.8 Update registerDomainsWithPort80Handler() to use route data
• 2.9 Improve forwardToNetworkProxy() to use route context
• 2.10 Update NetworkProxy integration in SmartProxy.ts
• 2.11 Test NetworkProxyBridge with pure route configurations
• 2.12 Add tests for certificate updates with routes

Phase 3: Remove Legacy Domain Configuration Code

• 3.1 Identify all imports of domain-config.ts and update them
• 3.2 Create route-based alternatives for any remaining domain-config usage
• 3.3 Delete domain-config.ts
• 3.4 Identify all imports of domain-manager.ts and update them
• 3.5 Delete domain-manager.ts
• 3.6 Update or remove forwarding-types.ts (route-based only)
• 3.7 Remove domain config support from Port80Handler
• 3.8 Update Port80HandlerOptions to use route configs
• 3.9 Update SmartProxy.ts to remove any remaining domain references
• 3.10 Remove domain-related imports in certificate components
• 3.11 Update IDomainForwardConfig to IRouteForwardConfig
• 3.12 Update all JSDoc comments to reference routes instead of domains
• 3.13 Run build to find any remaining type errors
• 3.14 Fix any remaining type errors from removed interfaces

Phase 4: Enhance Route Helpers and Configuration Experience

• 4.1 Create route-validators.ts with validation functions
• 4.2 Add validateRouteConfig() function for configuration validation
• 4.3 Add mergeRouteConfigs() utility function
• 4.4 Add findMatchingRoutes() helper function
• 4.5 Expand createStaticFileRoute() with more options
• 4.6 Add createApiRoute() helper for API gateway patterns
• 4.7 Add createAuthRoute() for authentication configurations
• 4.8 Add createWebSocketRoute() helper for WebSocket support
• 4.9 Create routePatterns.ts with common route patterns
• 4.10 Update route-helpers/index.ts to export all helpers
• 4.11 Add schema validation for route configurations
• 4.12 Create utils for route pattern testing
• 4.13 Update docs with pure route-based examples
• 4.14 Remove any legacy code examples from documentation

Phase 5: Testing and Validation

• 5.1 Update all tests to use pure route-based components
• 5.2 Create test cases for potential edge cases
• 5.3 Create a test for domain wildcard handling
• 5.4 Test all helper functions
• 5.5 Test certificate provisioning with routes
• 5.6 Test NetworkProxy integration with routes
• 5.7 Benchmark route matching performance
• 5.8 Compare memory usage before and after changes
• 5.9 Optimize route operations for large configurations
• 5.10 Verify public API matches documentation
• 5.11 Check for any backward compatibility issues
• 5.12 Ensure all examples in README work correctly
• 5.13 Run full test suite with new implementation
• 5.14 Create a final PR with all changes

Clean Break Approach

To keep our codebase as clean as possible, we are taking a clean break approach with NO migration or compatibility support for domain-based configuration. We will:

1. Completely remove all domain-based code
2. Not provide any migration utilities in the codebase
3. Focus solely on the route-based approach
4. Document the route-based API as the only supported method

This approach prioritizes codebase clarity over backward compatibility, which is appropriate since we've already made a clean break in the public API with v14.0.0.

File Changes

Files to Delete (Remove Completely)

• /ts/forwarding/config/domain-config.ts - Delete with no replacement
• /ts/forwarding/config/domain-manager.ts - Delete with no replacement
• /ts/forwarding/config/forwarding-types.ts - Delete with no replacement
• Any other domain-config related files found in the codebase

Files to Modify (Remove All Domain References)

• /ts/certificate/providers/cert-provisioner.ts - Complete rewrite to use routes only
• /ts/proxies/smart-proxy/network-proxy-bridge.ts - Remove all domain conversion code
• /ts/certificate/models/certificate-types.ts - Remove domain-based interfaces
• /ts/certificate/index.ts - Clean up all domain-related types and exports
• /ts/http/port80/port80-handler.ts - Update to work exclusively with routes
• /ts/proxies/smart-proxy/smart-proxy.ts - Remove any remaining domain references
• All other files with domain configuration imports - Remove or replace

New Files to Create (Route-Focused)

• /ts/proxies/smart-proxy/route-validators.ts - Validation utilities
• /ts/proxies/smart-proxy/route-utils.ts - Route utility functions
• /ts/proxies/smart-proxy/route-patterns.ts - Common route patterns

Benefits of Complete Refactoring

1. Codebase Simplicity:

   • No dual implementation or conversion logic
   • Simplified mental model for developers
   • Easier to maintain and extend

2. Performance Improvements:

   • Remove conversion overhead
   • More efficient route matching
   • Reduced memory footprint

3. Better Developer Experience:

   • Consistent API throughout
   • Cleaner documentation
   • More intuitive configuration patterns

4. Future-Proof Design:

   • Clear foundation for new features
   • Easier to implement advanced routing capabilities
   • Better integration with modern web patterns