smartproxy/readme.plan.md

SmartProxy Architecture Refactoring Plan

Overview

Refactor the proxy architecture to provide clearer separation of concerns between HTTP/HTTPS traffic handling and low-level connection routing.

Current Architecture Problems

1. NetworkProxy name doesn't clearly indicate it handles HTTP/HTTPS
2. HTTP parsing logic is duplicated in RouteConnectionHandler
3. Redirect and static route handling is embedded in SmartProxy
4. Unclear separation between TCP routing and HTTP processing

Proposed Architecture

HttpProxy (renamed from NetworkProxy)

Purpose: Handle all HTTP/HTTPS traffic with TLS termination

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 (ACME and static)

SmartProxy

Purpose: Low-level connection router and port manager

Responsibilities:

• Port management (listen on multiple ports)
• Route-based connection routing
• TLS passthrough (SNI-based routing)
• NFTables integration
• Delegate HTTP/HTTPS connections to HttpProxy
• Raw TCP proxying
• Connection lifecycle management

Implementation Plan

Phase 1: Rename and Reorganize NetworkProxy ✅

1. Rename NetworkProxy to HttpProxy

   • Renamed directory from network-proxy to http-proxy
   • Updated all imports and references

2. Update class and file names

   • 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

1. NetworkProxy class renamed to HttpProxy
2. Import paths change from network-proxy to http-proxy
3. Some type names may change for consistency

Rollback Plan

If issues arise:

1. Git revert to previous commit
2. Re-deploy previous version
3. Document lessons learned
4. Plan incremental changes