BREAKING CHANGE(smartproxy/configuration): Migrate SmartProxy to a fully unified route‐based configuration by removing legacy domain-based settings and conversion code. CertProvisioner, NetworkProxyBridge, and RouteManager now use IRouteConfig exclusively, and related legacy interfaces and files have been removed.
This commit is contained in:
426
readme.plan.md
426
readme.plan.md
@ -1,316 +1,158 @@
|
||||
# SmartProxy Fully Unified Configuration Plan (Updated)
|
||||
# SmartProxy Complete Route-Based Implementation Plan
|
||||
|
||||
## Project Goal
|
||||
Redesign SmartProxy's configuration for a more elegant, unified, and comprehensible approach by:
|
||||
1. Creating a single, unified configuration model that covers both "where to listen" and "how to forward"
|
||||
2. Eliminating the confusion between domain configs and port forwarding
|
||||
3. Providing a clear, declarative API that makes the intent obvious
|
||||
4. Enhancing maintainability and extensibility for future features
|
||||
5. Completely removing legacy code to eliminate technical debt
|
||||
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 Issues
|
||||
## 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
|
||||
|
||||
The current approach has several issues:
|
||||
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
|
||||
|
||||
1. **Dual Configuration Systems**:
|
||||
- Port configuration (`fromPort`, `toPort`, `globalPortRanges`) for "where to listen"
|
||||
- Domain configuration (`domainConfigs`) for "how to forward"
|
||||
- Unclear relationship between these two systems
|
||||
## Implementation Checklist
|
||||
|
||||
2. **Mixed Concerns**:
|
||||
- Port management is mixed with forwarding logic
|
||||
- Domain routing is separated from port listening
|
||||
- Security settings defined in multiple places
|
||||
### 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
|
||||
|
||||
3. **Complex Logic**:
|
||||
- PortRangeManager must coordinate with domain configuration
|
||||
- Implicit rules for handling connections based on port and domain
|
||||
### 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
|
||||
|
||||
4. **Difficult to Understand and Configure**:
|
||||
- Two separate configuration hierarchies that must work together
|
||||
- Unclear which settings take precedence
|
||||
### 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
|
||||
|
||||
## Proposed Solution: Fully Unified Routing Configuration
|
||||
### 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
|
||||
|
||||
Replace both port and domain configuration with a single, unified configuration:
|
||||
### 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
|
||||
|
||||
```typescript
|
||||
// The core unified configuration interface
|
||||
interface IRouteConfig {
|
||||
// What to match
|
||||
match: {
|
||||
// Listen on these ports (required)
|
||||
ports: number | number[] | Array<{ from: number, to: number }>;
|
||||
|
||||
// Optional domain patterns to match (default: all domains)
|
||||
domains?: string | string[];
|
||||
|
||||
// Advanced matching criteria
|
||||
path?: string; // Match specific paths
|
||||
clientIp?: string[]; // Match specific client IPs
|
||||
tlsVersion?: string[]; // Match specific TLS versions
|
||||
};
|
||||
|
||||
// What to do with matched traffic
|
||||
action: {
|
||||
// Basic routing
|
||||
type: 'forward' | 'redirect' | 'block';
|
||||
|
||||
// Target for forwarding
|
||||
target?: {
|
||||
host: string | string[]; // Support single host or round-robin
|
||||
port: number;
|
||||
preservePort?: boolean; // Use incoming port as target port
|
||||
};
|
||||
|
||||
// TLS handling
|
||||
tls?: {
|
||||
mode: 'passthrough' | 'terminate' | 'terminate-and-reencrypt';
|
||||
certificate?: 'auto' | { // Auto = use ACME
|
||||
key: string;
|
||||
cert: string;
|
||||
};
|
||||
};
|
||||
|
||||
// For redirects
|
||||
redirect?: {
|
||||
to: string; // URL or template with {domain}, {port}, etc.
|
||||
status: 301 | 302 | 307 | 308;
|
||||
};
|
||||
|
||||
// Security options
|
||||
security?: {
|
||||
allowedIps?: string[];
|
||||
blockedIps?: string[];
|
||||
maxConnections?: number;
|
||||
authentication?: {
|
||||
type: 'basic' | 'digest' | 'oauth';
|
||||
// Auth-specific options
|
||||
};
|
||||
};
|
||||
|
||||
// Advanced options
|
||||
advanced?: {
|
||||
timeout?: number;
|
||||
headers?: Record<string, string>;
|
||||
keepAlive?: boolean;
|
||||
// etc.
|
||||
};
|
||||
};
|
||||
|
||||
// Optional metadata
|
||||
name?: string; // Human-readable name for this route
|
||||
description?: string; // Description of the route's purpose
|
||||
priority?: number; // Controls matching order (higher = matched first)
|
||||
tags?: string[]; // Arbitrary tags for categorization
|
||||
}
|
||||
## Clean Break Approach
|
||||
|
||||
// Main SmartProxy options
|
||||
interface ISmartProxyOptions {
|
||||
// The unified configuration array (required)
|
||||
routes: IRouteConfig[];
|
||||
|
||||
// Global/default settings
|
||||
defaults?: {
|
||||
target?: {
|
||||
host: string;
|
||||
port: number;
|
||||
};
|
||||
security?: {
|
||||
// Global security defaults
|
||||
};
|
||||
tls?: {
|
||||
// Global TLS defaults
|
||||
};
|
||||
// ...other defaults
|
||||
};
|
||||
|
||||
// Other global settings remain (acme, etc.)
|
||||
acme?: IAcmeOptions;
|
||||
|
||||
// Advanced settings remain as well
|
||||
// ...
|
||||
}
|
||||
```
|
||||
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:
|
||||
|
||||
## Revised Implementation Plan
|
||||
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
|
||||
|
||||
### Phase 1: Core Design & Interface Definition
|
||||
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.
|
||||
|
||||
1. **Define New Core Interfaces**:
|
||||
- Create `IRouteConfig` interface with `match` and `action` branches
|
||||
- Define all sub-interfaces for matching and actions
|
||||
- Create new `ISmartProxyOptions` to use `routes` array exclusively
|
||||
- Define template variable system for dynamic values
|
||||
## File Changes
|
||||
|
||||
2. **Create Helper Functions**:
|
||||
- `createRoute()` - Basic route creation with reasonable defaults
|
||||
- `createHttpRoute()`, `createHttpsRoute()`, `createRedirect()` - Common scenarios
|
||||
- `createLoadBalancer()` - For multi-target setups
|
||||
- `mergeSecurity()`, `mergeDefaults()` - For combining configs
|
||||
### 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
|
||||
|
||||
3. **Design Router**:
|
||||
- Decision tree for route matching algorithm
|
||||
- Priority system for route ordering
|
||||
- Optimized lookup strategy for fast routing
|
||||
### 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
|
||||
|
||||
### Phase 2: Core Implementation
|
||||
### 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
|
||||
|
||||
1. **Create RouteManager**:
|
||||
- Build a new RouteManager to replace both PortRangeManager and DomainConfigManager
|
||||
- Implement port and domain matching in one unified system
|
||||
- Create efficient route lookup algorithms
|
||||
## Benefits of Complete Refactoring
|
||||
|
||||
2. **Implement New ConnectionHandler**:
|
||||
- Create a new ConnectionHandler built from scratch for routes
|
||||
- Implement the routing logic with the new match/action pattern
|
||||
- Support template processing for headers and other dynamic values
|
||||
1. **Codebase Simplicity**:
|
||||
- No dual implementation or conversion logic
|
||||
- Simplified mental model for developers
|
||||
- Easier to maintain and extend
|
||||
|
||||
3. **Implement New SmartProxy Core**:
|
||||
- Create new SmartProxy implementation using routes exclusively
|
||||
- Build network servers based on port specifications
|
||||
- Manage TLS contexts and certificates
|
||||
2. **Performance Improvements**:
|
||||
- Remove conversion overhead
|
||||
- More efficient route matching
|
||||
- Reduced memory footprint
|
||||
|
||||
### Phase 3: Legacy Code Removal
|
||||
|
||||
1. **Identify Legacy Components**:
|
||||
- Create an inventory of all files and components to be removed
|
||||
- Document dependencies between legacy components
|
||||
- Create a removal plan that minimizes disruption
|
||||
|
||||
2. **Remove Legacy Components**:
|
||||
- Remove PortRangeManager and related code
|
||||
- Remove DomainConfigManager and related code
|
||||
- Remove old ConnectionHandler implementation
|
||||
- Remove other legacy components
|
||||
|
||||
3. **Clean Interface Adaptations**:
|
||||
- Remove all legacy interfaces and types
|
||||
- Update type exports to only expose route-based interfaces
|
||||
- Remove any adapter or backward compatibility code
|
||||
|
||||
### Phase 4: Updated Documentation & Examples
|
||||
|
||||
1. **Update Core Documentation**:
|
||||
- Rewrite README.md with a focus on route-based configuration exclusively
|
||||
- Create interface reference documentation
|
||||
- Document all template variables
|
||||
|
||||
2. **Create Example Library**:
|
||||
- Common configuration patterns using the new API
|
||||
- Complex use cases for advanced features
|
||||
- Infrastructure-as-code examples
|
||||
|
||||
3. **Add Validation Tools**:
|
||||
- Configuration validator to check for issues
|
||||
- Schema definitions for IDE autocomplete
|
||||
- Runtime validation helpers
|
||||
|
||||
### Phase 5: Testing
|
||||
|
||||
1. **Unit Tests**:
|
||||
- Test route matching logic
|
||||
- Validate priority handling
|
||||
- Test template processing
|
||||
|
||||
2. **Integration Tests**:
|
||||
- Verify full proxy flows with the new system
|
||||
- Test complex routing scenarios
|
||||
- Ensure all features work as expected
|
||||
|
||||
3. **Performance Testing**:
|
||||
- Benchmark routing performance
|
||||
- Evaluate memory usage
|
||||
- Test with large numbers of routes
|
||||
|
||||
## Implementation Strategy
|
||||
|
||||
### Code Organization
|
||||
|
||||
1. **New Files**:
|
||||
- `route-config.ts` - Core route interfaces
|
||||
- `route-manager.ts` - Route matching and management
|
||||
- `route-connection-handler.ts` - Connection handling with routes
|
||||
- `route-smart-proxy.ts` - Main SmartProxy implementation
|
||||
- `template-engine.ts` - For variable substitution
|
||||
|
||||
2. **File Removal**:
|
||||
- Remove `port-range-manager.ts`
|
||||
- Remove `domain-config-manager.ts`
|
||||
- Remove legacy interfaces and adapter code
|
||||
- Remove backward compatibility shims
|
||||
|
||||
### Transition Strategy
|
||||
|
||||
1. **Breaking Change Approach**:
|
||||
- This will be a major version update with breaking changes
|
||||
- No backward compatibility will be maintained
|
||||
- Clear migration documentation will guide users to the new API
|
||||
|
||||
2. **Package Structure**:
|
||||
- `@push.rocks/smartproxy` package will be updated to v14.0.0
|
||||
- Legacy code fully removed, only route-based API exposed
|
||||
- Support documentation provided for migration
|
||||
|
||||
3. **Migration Documentation**:
|
||||
- Provide a migration guide with examples
|
||||
- Show equivalent route configurations for common legacy patterns
|
||||
- Offer code transformation helpers for complex setups
|
||||
|
||||
## Benefits of the Clean Approach
|
||||
|
||||
1. **Reduced Complexity**:
|
||||
- No overlapping or conflicting configuration systems
|
||||
- No dual maintenance of backward compatibility code
|
||||
- Simplified internal architecture
|
||||
|
||||
2. **Cleaner Code Base**:
|
||||
- Removal of technical debt
|
||||
- Better separation of concerns
|
||||
- More maintainable codebase
|
||||
|
||||
3. **Better User Experience**:
|
||||
- Consistent, predictable API
|
||||
- No confusing overlapping options
|
||||
- Clear documentation of one approach, not two
|
||||
3. **Better Developer Experience**:
|
||||
- Consistent API throughout
|
||||
- Cleaner documentation
|
||||
- More intuitive configuration patterns
|
||||
|
||||
4. **Future-Proof Design**:
|
||||
- Easier to extend with new features
|
||||
- Better performance without legacy overhead
|
||||
- Cleaner foundation for future enhancements
|
||||
|
||||
## Migration Support
|
||||
|
||||
While we're removing backward compatibility from the codebase, we'll provide extensive migration support:
|
||||
|
||||
1. **Migration Guide**:
|
||||
- Detailed documentation on moving from legacy to route-based config
|
||||
- Pattern-matching examples for all common use cases
|
||||
- Troubleshooting guide for common migration issues
|
||||
|
||||
2. **Conversion Tool**:
|
||||
- Provide a standalone one-time conversion tool
|
||||
- Takes legacy configuration and outputs route-based equivalents
|
||||
- Will not be included in the main package to avoid bloat
|
||||
|
||||
3. **Version Policy**:
|
||||
- Maintain the legacy version (13.x) for security updates
|
||||
- Make the route-based version a clear major version change (14.0.0)
|
||||
- Clearly communicate the breaking changes
|
||||
|
||||
## Timeline and Versioning
|
||||
|
||||
1. **Development**:
|
||||
- Develop route-based implementation in a separate branch
|
||||
- Complete full test coverage of new implementation
|
||||
- Ensure documentation is complete
|
||||
|
||||
2. **Release**:
|
||||
- Release as version 14.0.0
|
||||
- Clearly mark as breaking change
|
||||
- Provide migration guide at release time
|
||||
|
||||
3. **Support**:
|
||||
- Offer extended support for migration questions
|
||||
- Consider maintaining security updates for v13.x for 6 months
|
||||
- Focus active development on route-based version only
|
||||
- Clear foundation for new features
|
||||
- Easier to implement advanced routing capabilities
|
||||
- Better integration with modern web patterns
|
||||
Reference in New Issue
Block a user