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 major 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

### Completed Phases:
1. ✅ **Phase 1:** CertProvisioner has been fully refactored to work natively with routes
2. ✅ **Phase 2:** NetworkProxyBridge now works directly with route configurations

### Remaining Tasks:
1. Some legacy domain-based code still exists in the codebase
2. Deprecated methods remain for backward compatibility
3. Final cleanup of legacy interfaces and types is needed

## Implementation Checklist

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

### Phase 2: Refactor NetworkProxyBridge for Direct Route Processing ✅
- [x] 2.1 Update NetworkProxyBridge constructor to work directly with routes
- [x] 2.2 Refactor syncRoutesToNetworkProxy() to eliminate domain conversion
- [x] 2.3 Rename convertRoutesToNetworkProxyConfigs() to mapRoutesToNetworkProxyConfigs()
- [x] 2.4 Maintain syncDomainConfigsToNetworkProxy() as deprecated wrapper
- [x] 2.5 Implement direct mapping from routes to NetworkProxy configs
- [x] 2.6 Update handleCertificateEvent() to work with routes
- [x] 2.7 Update applyExternalCertificate() to use route information
- [x] 2.8 Update registerDomainsWithPort80Handler() to extract domains from routes
- [x] 2.9 Update certificate request flow to track route references
- [x] 2.10 Test NetworkProxyBridge with pure route configurations
- [x] 2.11 Successfully build and run all tests

### Phase 3: Remove Legacy Domain Configuration Code
- [x] 3.1 Identify all imports of domain-config.ts and update them
- [x] 3.2 Create route-based alternatives for any remaining domain-config usage
- [x] 3.3 Delete domain-config.ts
- [x] 3.4 Identify all imports of domain-manager.ts and update them
- [x] 3.5 Delete domain-manager.ts
- [x] 3.6 Update forwarding-types.ts (route-based only)
- [x] 3.7 Add route-based domain support to Port80Handler
- [x] 3.8 Create IPort80RouteOptions and extractPort80RoutesFromRoutes utility
- [x] 3.9 Update SmartProxy.ts to use route-based domain management
- [x] 3.10 Provide compatibility layer for domain-based interfaces
- [x] 3.11 Update IDomainForwardConfig to IRouteForwardConfig
- [x] 3.12 Update JSDoc comments to reference routes instead of domains
- [x] 3.13 Run build to find any remaining type errors
- [x] 3.14 Fix all type errors to ensure successful build
- [x] 3.15 Update tests to use route-based approach instead of domain-based
- [x] 3.16 Fix all failing tests
- [x] 3.17 Verify build and test suite pass successfully

### Phase 4: Enhance Route Helpers and Configuration Experience ✅
- [x] 4.1 Create route-validators.ts with validation functions
- [x] 4.2 Add validateRouteConfig() function for configuration validation
- [x] 4.3 Add mergeRouteConfigs() utility function
- [x] 4.4 Add findMatchingRoutes() helper function
- [x] 4.5 Expand createStaticFileRoute() with more options
- [x] 4.6 Add createApiRoute() helper for API gateway patterns
- [x] 4.7 Add createAuthRoute() for authentication configurations
- [x] 4.8 Add createWebSocketRoute() helper for WebSocket support
- [x] 4.9 Create routePatterns.ts with common route patterns
- [x] 4.10 Update utils/index.ts to export all helpers
- [x] 4.11 Add schema validation for route configurations
- [x] 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)
- [x] `/ts/forwarding/config/domain-config.ts` - Deleted with no replacement
- [x] `/ts/forwarding/config/domain-manager.ts` - Deleted with no replacement
- [ ] `/ts/forwarding/config/forwarding-types.ts` - Keep for backward compatibility
- [x] Any domain-config related tests have been updated to use route-based approach

### Files to Modify (Remove All Domain References)
- [x] `/ts/certificate/providers/cert-provisioner.ts` - Complete rewrite to use routes only ✅
- [x] `/ts/proxies/smart-proxy/network-proxy-bridge.ts` - Direct route processing implementation ✅
- [x] `/ts/certificate/models/certificate-types.ts` - Updated with route-based interfaces ✅
- [x] `/ts/certificate/index.ts` - Cleaned up domain-related types and exports
- [x] `/ts/http/port80/port80-handler.ts` - Updated to work exclusively with routes
- [x] `/ts/proxies/smart-proxy/smart-proxy.ts` - Removed domain references
- [x] `test/test.forwarding.ts` - Updated to use route-based approach
- [x] `test/test.forwarding.unit.ts` - Updated to use route-based approach

### New Files to Create (Route-Focused)
- [x] `/ts/proxies/smart-proxy/utils/route-helpers.ts` - Created with helper functions for common route configurations
- [x] `/ts/proxies/smart-proxy/utils/route-migration-utils.ts` - Added migration utilities from domains to routes
- [x] `/ts/proxies/smart-proxy/utils/route-validators.ts` - Validation utilities for route configurations
- [x] `/ts/proxies/smart-proxy/utils/route-utils.ts` - Additional route utility functions
- [x] `/ts/proxies/smart-proxy/utils/route-patterns.ts` - Common route patterns for easy configuration
- [x] `/ts/proxies/smart-proxy/utils/index.ts` - Central export point for all route utilities

## 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