@push.rocks/smartproxy 13.1.2 → 15.0.0

package/readme.plan.md

@@ -1,255 +1,316 @@
-# SmartProxy Interface & Type Naming Standardization Plan
+# SmartProxy Fully Unified Configuration Plan (Updated)
 
 ## Project Goal
-Standardize interface and type naming throughout the SmartProxy codebase to improve maintainability, readability, and developer experience by:
-1. Ensuring all interfaces are prefixed with "I"
-2. Ensuring all type aliases are prefixed with "T"
-3. Maintaining backward compatibility through type aliases
-4. Updating documentation to reflect naming conventions
-
-## Phase 2: Core Module Standardization
-
-- [ ] Update core module interfaces and types
-  - [ ] Rename interfaces in `ts/core/models/common-types.ts`
-    - [ ] `AcmeOptions` → `IAcmeOptions`
-    - [ ] `DomainOptions` → `IDomainOptions`
-    - [ ] Other common interfaces
-  - [ ] Add backward compatibility aliases
-  - [ ] Update imports throughout core module
-
-- [ ] Update core utility type definitions
-  - [ ] Update `ts/core/utils/validation-utils.ts`
-  - [ ] Update `ts/core/utils/ip-utils.ts`
-  - [ ] Standardize event type definitions
-
-- [ ] Test core module changes
-  - [ ] Run unit tests for core modules
-  - [ ] Verify type compatibility
-  - [ ] Ensure backward compatibility
-
-## Phase 3: Certificate Module Standardization
-
-- [ ] Update certificate interfaces
-  - [ ] Rename interfaces in `ts/certificate/models/certificate-types.ts`
-    - [ ] `CertificateData` → `ICertificateData`
-    - [ ] `Certificates` → `ICertificates`
-    - [ ] `CertificateFailure` → `ICertificateFailure`
-    - [ ] `CertificateExpiring` → `ICertificateExpiring`
-    - [ ] `ForwardConfig` → `IForwardConfig`
-    - [ ] `DomainForwardConfig` → `IDomainForwardConfig`
-  - [ ] Update ACME challenge interfaces
-  - [ ] Standardize storage provider interfaces
-
-- [ ] Ensure certificate provider compatibility
-  - [ ] Update provider implementations
-  - [ ] Rename internal interfaces
-  - [ ] Maintain public API compatibility
-
-- [ ] Test certificate module
-  - [ ] Verify ACME functionality
-  - [ ] Test certificate provisioning
-  - [ ] Validate challenge handling
-
-## Phase 4: Forwarding System Standardization
-
-- [ ] Update forwarding configuration interfaces
-  - [ ] Rename interfaces in `ts/forwarding/config/forwarding-types.ts`
-    - [ ] `TargetConfig` → `ITargetConfig`
-    - [ ] `HttpOptions` → `IHttpOptions`
-    - [ ] `HttpsOptions` → `IHttpsOptions`
-    - [ ] `AcmeForwardingOptions` → `IAcmeForwardingOptions`
-    - [ ] `SecurityOptions` → `ISecurityOptions`
-    - [ ] `AdvancedOptions` → `IAdvancedOptions`
-    - [ ] `ForwardConfig` → `IForwardConfig`
-  - [ ] Rename type definitions
-    - [ ] `ForwardingType` → `TForwardingType`
-  - [ ] Update domain configuration interfaces
-
-- [ ] Standardize handler interfaces
-  - [ ] Update base handler interfaces
-  - [ ] Rename handler-specific interfaces
-  - [ ] Update factory interfaces
-
-- [ ] Verify forwarding system functionality
-  - [ ] Test all forwarding types
-  - [ ] Verify configuration parsing
-  - [ ] Ensure backward compatibility
-
-## Phase 5: Proxy Implementation Standardization
-
-- [ ] Update SmartProxy interfaces
-  - [ ] Rename interfaces in `ts/proxies/smart-proxy/models/interfaces.ts`
-  - [ ] Update domain configuration interfaces
-  - [ ] Standardize manager interfaces
-
-- [ ] Update NetworkProxy interfaces
-  - [ ] Rename in `ts/proxies/network-proxy/models/types.ts`
-    - [ ] `NetworkProxyOptions` → `INetworkProxyOptions`
-    - [ ] `CertificateEntry` → `ICertificateEntry`
-    - [ ] `ReverseProxyConfig` → `IReverseProxyConfig`
-    - [ ] `ConnectionEntry` → `IConnectionEntry`
-    - [ ] `WebSocketWithHeartbeat` → `IWebSocketWithHeartbeat`
-    - [ ] `Logger` → `ILogger`
-  - [ ] Update request handler interfaces
-  - [ ] Standardize connection interfaces
-
-- [ ] Update NfTablesProxy interfaces
-  - [ ] Rename interfaces in `ts/proxies/nftables-proxy/models/interfaces.ts`
-  - [ ] Update configuration interfaces
-  - [ ] Standardize firewall rule interfaces
-
-- [ ] Test proxy implementations
-  - [ ] Verify SmartProxy functionality
-  - [ ] Test NetworkProxy with renamed interfaces
-  - [ ] Validate NfTablesProxy operations
-
-## Phase 6: HTTP & TLS Module Standardization
-
-- [ ] Update HTTP interfaces
-  - [ ] Rename in `ts/http/port80/acme-interfaces.ts`
-    - [ ] `SmartAcmeCert` → `ISmartAcmeCert`
-    - [ ] `SmartAcmeOptions` → `ISmartAcmeOptions`
-    - [ ] `Http01Challenge` → `IHttp01Challenge`
-    - [ ] `SmartAcme` → `ISmartAcme`
-  - [ ] Standardize router interfaces
-  - [ ] Update port80 handler interfaces
-  - [ ] Update redirect interfaces
-
-- [ ] Update TLS/SNI interfaces
-  - [ ] Standardize SNI handler interfaces
-  - [ ] Update client hello parser types
-  - [ ] Rename TLS alert interfaces
-
-- [ ] Test HTTP & TLS functionality
-  - [ ] Verify router operation
-  - [ ] Test SNI extraction
-  - [ ] Validate redirect functionality
-
-## Phase 7: Backward Compatibility Layer
-
-- [ ] Implement comprehensive type aliases
-  - [ ] Create aliases for all renamed interfaces
-  - [ ] Add deprecation notices via JSDoc
-  - [ ] Ensure all exports include both named versions
-
-- [ ] Update main entry point
-  - [ ] Update `ts/index.ts` with all exports
-  - [ ] Include both prefixed and non-prefixed names
-  - [ ] Organize exports by module
-
-- [ ] Add compatibility documentation
-  - [ ] Document renaming strategy
-  - [ ] Provide migration examples
-  - [ ] Create deprecation timeline
-
-## Phase 8: Documentation & Examples
-
-- [ ] Update README and API documentation
-  - [ ] Update interface references in README.md
-  - [ ] Document naming convention in README.md
-  - [ ] Update API reference documentation
-
-- [ ] Update examples
-  - [ ] Modify example code to use new interface names
-  - [ ] Add compatibility notes
-  - [ ] Create migration examples
-
-- [ ] Add contributor guidelines
-  - [ ] Document naming conventions
-  - [ ] Add interface/type style guide
-  - [ ] Update PR templates
-
-## Phase 9: Testing & Validation
-
-- [ ] Run comprehensive test suite
-  - [ ] Run all unit tests
-  - [ ] Execute integration tests
-  - [ ] Verify example code
-
-- [ ] Build type declarations
-  - [ ] Generate TypeScript declaration files
-  - [ ] Verify exported types
-  - [ ] Validate documentation generation
-
-- [ ] Final compatibility check
-  - [ ] Verify import compatibility
-  - [ ] Test with existing dependent projects
-  - [ ] Validate backward compatibility claims
+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
 
-### Naming Pattern Rules
-
-1. **Interfaces**:
-   - All interfaces should be prefixed with "I"
-   - Example: `DomainConfig` → `IDomainConfig`
-
-2. **Type Aliases**:
-   - All type aliases should be prefixed with "T"
-   - Example: `ForwardingType` → `TForwardingType`
-
-3. **Enums**:
-   - Enums should be named in PascalCase without prefix
-   - Example: `CertificateSource`
-
-4. **Backward Compatibility**:
-   - No Backward compatibility. Remove old names.
-
-### Module Implementation Order
-
-1. Core module
-2. Certificate module
-3. Forwarding module
-4. Proxy implementations
-5. HTTP & TLS modules
-6. Main exports and entry points
-
-### Testing Strategy
-
-For each module:
-1. Rename interfaces and types
-2. Add backward compatibility aliases
-3. Update imports throughout the module
-4. Run tests to verify functionality
-5. Commit changes module by module
-
-## File-Specific Changes
-
-### Core Module Files
-- `ts/core/models/common-types.ts` - Primary interfaces
-- `ts/core/utils/validation-utils.ts` - Validation type definitions
-- `ts/core/utils/ip-utils.ts` - IP utility type definitions
-- `ts/core/utils/event-utils.ts` - Event type definitions 
-
-### Certificate Module Files
-- `ts/certificate/models/certificate-types.ts` - Certificate interfaces
-- `ts/certificate/acme/acme-factory.ts` - ACME factory types
-- `ts/certificate/providers/cert-provisioner.ts` - Provider interfaces
-- `ts/certificate/storage/file-storage.ts` - Storage interfaces
-
-### Forwarding Module Files
-- `ts/forwarding/config/forwarding-types.ts` - Forwarding interfaces and types
-- `ts/forwarding/config/domain-config.ts` - Domain configuration
-- `ts/forwarding/factory/forwarding-factory.ts` - Factory interfaces
-- `ts/forwarding/handlers/*.ts` - Handler interfaces
-
-### Proxy Module Files
-- `ts/proxies/network-proxy/models/types.ts` - NetworkProxy interfaces
-- `ts/proxies/smart-proxy/models/interfaces.ts` - SmartProxy interfaces
-- `ts/proxies/nftables-proxy/models/interfaces.ts` - NfTables interfaces
-- `ts/proxies/smart-proxy/connection-manager.ts` - Connection types
-
-### HTTP/TLS Module Files
-- `ts/http/models/http-types.ts` - HTTP module interfaces
-- `ts/http/port80/acme-interfaces.ts` - ACME interfaces
-- `ts/tls/sni/client-hello-parser.ts` - TLS parser types
-- `ts/tls/alerts/tls-alert.ts` - TLS alert interfaces
-
-## Success Criteria
-
-- All interfaces are prefixed with "I"
-- All type aliases are prefixed with "T"
-- All tests pass with new naming conventions
-- Documentation is updated with new naming conventions
-- Backward compatibility is maintained through type aliases
-- Declaration files correctly export both naming conventions
+### 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

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartproxy',
-  version: '13.1.2',
-  description: 'A powerful proxy package that effectively handles high traffic, with features such as SSL/TLS support, port proxying, WebSocket handling, dynamic routing with authentication options, and automatic ACME certificate management.'
+  version: '15.0.0',
+  description: 'A powerful proxy package with unified route-based configuration for high traffic management. Features include SSL/TLS support, flexible routing patterns, WebSocket handling, advanced security options, and automatic ACME certificate management.'
 }

package/ts/proxies/smart-proxy/index.ts

@@ -1,5 +1,7 @@
 /**
  * SmartProxy implementation
+ *
+ * Version 14.0.0: Unified Route-Based Configuration API
  */
 // Re-export models
 export * from './models/index.js';
@@ -7,12 +9,26 @@ export * from './models/index.js';
 // Export the main SmartProxy class
 export { SmartProxy } from './smart-proxy.js';
 
-// Export supporting classes
+// Export core supporting classes
 export { ConnectionManager } from './connection-manager.js';
 export { SecurityManager } from './security-manager.js';
-export { DomainConfigManager } from './domain-config-manager.js';
 export { TimeoutManager } from './timeout-manager.js';
 export { TlsManager } from './tls-manager.js';
 export { NetworkProxyBridge } from './network-proxy-bridge.js';
-export { PortRangeManager } from './port-range-manager.js';
-export { ConnectionHandler } from './connection-handler.js';
+
+// Export route-based components
+export { RouteManager } from './route-manager.js';
+export { RouteConnectionHandler } from './route-connection-handler.js';
+
+// Export route helpers for configuration
+export {
+  createRoute,
+  createHttpRoute,
+  createHttpsRoute,
+  createPassthroughRoute,
+  createRedirectRoute,
+  createHttpToHttpsRedirect,
+  createBlockRoute,
+  createLoadBalancerRoute,
+  createHttpsServer
+} from './route-helpers.js';

package/ts/proxies/smart-proxy/models/index.ts

@@ -2,3 +2,7 @@
  * SmartProxy models
  */
 export * from './interfaces.js';
+export * from './route-types.js';
+
+// Re-export IRoutedSmartProxyOptions explicitly to avoid ambiguity
+export type { ISmartProxyOptions as IRoutedSmartProxyOptions } from './interfaces.js';