smartproxy/readme.plan.md

# SmartProxy Fully Unified Configuration Plan (Updated)

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

## Current Issues

The current approach has several issues:

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

2. **Mixed Concerns**:
   - Port management is mixed with forwarding logic
   - Domain routing is separated from port listening
   - Security settings defined in multiple places

3. **Complex Logic**:
   - PortRangeManager must coordinate with domain configuration
   - Implicit rules for handling connections based on port and domain

4. **Difficult to Understand and Configure**:
   - Two separate configuration hierarchies that must work together
   - Unclear which settings take precedence

## Proposed Solution: Fully Unified Routing Configuration

Replace both port and domain configuration with a single, unified configuration:

```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
}

// 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
  // ...
}
```

## Revised Implementation Plan

### Phase 1: Core Design & Interface Definition

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

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

3. **Design Router**:
   - Decision tree for route matching algorithm
   - Priority system for route ordering
   - Optimized lookup strategy for fast routing

### Phase 2: Core Implementation

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

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

3. **Implement New SmartProxy Core**:
   - Create new SmartProxy implementation using routes exclusively
   - Build network servers based on port specifications
   - Manage TLS contexts and certificates

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

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