smartproxy/readme.plan.md

SmartProxy v19.4.0 - Completed Refactoring

Overview

SmartProxy has been successfully refactored with clearer separation of concerns between HTTP/HTTPS traffic handling and low-level connection routing. Version 19.4.0 introduces global ACME configuration and enhanced route management.

Current Architecture (v19.4.0)

HttpProxy (formerly NetworkProxy)

Purpose: Handle all HTTP/HTTPS traffic with TLS termination

Current Responsibilities:

• TLS termination for HTTPS
• HTTP/1.1 and HTTP/2 protocol handling
• HTTP request/response parsing
• HTTP to HTTPS redirects
• ACME challenge handling
• Static route handlers
• WebSocket protocol upgrades
• Connection pooling for backend servers
• Certificate management integration

SmartProxy

Purpose: Central API for all proxy needs with route-based configuration

Current Responsibilities:

• Port management (listen on multiple ports)
• Route-based connection routing
• TLS passthrough (SNI-based routing)
• NFTables integration
• Certificate management via SmartCertManager
• Raw TCP proxying
• Connection lifecycle management
• Global ACME configuration (v19+)

Completed Implementation

Phase 1: Rename and Reorganize ✅

• NetworkProxy renamed to HttpProxy
• Directory structure reorganized
• All imports and references updated

Phase 2: Certificate Management ✅

• Unified certificate management in SmartCertManager
• Global ACME configuration support (v19+)
• Route-level certificate overrides
• Automatic renewal system
  • Renamed network-proxy.ts to http-proxy.ts
  • Updated NetworkProxy class to HttpProxy class
  • Updated all type definitions and interfaces

3. Update exports
   • Updated exports in ts/index.ts
   • Fixed imports across the codebase

Phase 2: Extract HTTP Logic from SmartProxy ✅

1. Create HTTP handler modules in HttpProxy

   • Created handlers directory with:
     • redirect-handler.ts - HTTP redirect logic
     • static-handler.ts - Static/ACME route handling
     • index.ts - Module exports

2. Move HTTP parsing from RouteConnectionHandler

   • Updated handleRedirectAction to delegate to RedirectHandler
   • Updated handleStaticAction to delegate to StaticHandler
   • Removed duplicated HTTP parsing logic

3. Clean up references and naming

   • Updated all NetworkProxy references to HttpProxy
   • Renamed config properties: useNetworkProxy → useHttpProxy
   • Renamed config properties: networkProxyPort → httpProxyPort
   • Fixed HttpProxyBridge methods and references

Phase 3: Simplify SmartProxy

1. Update RouteConnectionHandler

   • Remove embedded HTTP parsing
   • Delegate HTTP routes to HttpProxy
   • Focus on connection routing only

2. Simplified route handling

   // Simplified handleRedirectAction
   private handleRedirectAction(socket, record, route) {
     // Delegate to HttpProxy
     this.httpProxy.handleRedirect(socket, route);
   }
   
   // Simplified handleStaticAction
   private handleStaticAction(socket, record, route) {
     // Delegate to HttpProxy
     this.httpProxy.handleStatic(socket, route);
   }
   

3. Update NetworkProxyBridge

   • Rename to HttpProxyBridge
   • Update integration points

Phase 4: Consolidate HTTP Utilities ✅

1. Move HTTP types to http-proxy

   • Created consolidated http-types.ts in ts/proxies/http-proxy/models/
   • Includes HTTP status codes, error classes, and interfaces
   • Added helper functions like getStatusText()

2. Clean up ts/http directory

   • Kept only router functionality
   • Replaced local HTTP types with re-exports from HttpProxy
   • Updated imports throughout the codebase to use consolidated types

Phase 5: Update Tests and Documentation ✅

1. Update test files

   • Renamed NetworkProxy references to HttpProxy
   • Renamed test files to match new naming
   • Updated imports and references throughout tests
   • Fixed certificate manager method names

2. Update documentation

   • Updated README to reflect HttpProxy naming
   • Updated architecture descriptions
   • Updated usage examples
   • Fixed all API documentation references

Migration Steps

1. Create feature branch: refactor/http-proxy-consolidation
2. Phase 1: Rename NetworkProxy (1 day)
3. Phase 2: Extract HTTP logic (2 days)
4. Phase 3: Simplify SmartProxy (1 day)
5. Phase 4: Consolidate utilities (1 day)
6. Phase 5: Update tests/docs (1 day)
7. Integration testing (1 day)
8. Code review and merge

Benefits

1. Clear Separation: HTTP/HTTPS handling is clearly separated from TCP routing
2. Better Naming: HttpProxy clearly indicates its purpose
3. No Duplication: HTTP parsing logic exists in one place
4. Maintainability: Easier to modify HTTP handling without affecting routing
5. Testability: Each component has a single responsibility
6. Performance: Optimized paths for different traffic types

Future Enhancements

After this refactoring, we can more easily add:

1. HTTP/3 (QUIC) support in HttpProxy
2. Advanced HTTP features (compression, caching)
3. HTTP middleware system
4. Protocol-specific optimizations
5. Better HTTP/2 multiplexing

Breaking Changes from v18 to v19

1. NetworkProxy class renamed to HttpProxy
2. Import paths change from network-proxy to http-proxy
3. Global ACME configuration now available at the top level
4. Certificate management unified under SmartCertManager

Future Enhancements

1. HTTP/3 (QUIC) support in HttpProxy
2. Advanced HTTP features (compression, caching)
3. HTTP middleware system
4. Protocol-specific optimizations
5. Better HTTP/2 multiplexing
6. Enhanced monitoring and metrics

Key Features in v19.4.0

1. Global ACME Configuration: Default settings for all routes with certificate: 'auto'
2. Enhanced Route Management: Better separation between routing and certificate management
3. Improved Test Coverage: Fixed test exports and port bindings
4. Better Error Messages: Clear guidance for ACME configuration issues
5. Non-Privileged Port Support: Examples for development environments