push.rocks/smartproxy
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
smartproxy/readme.plan.md

10 KiB
Raw Blame History

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:

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