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**
   ```typescript
   // 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