smartproxy/readme.plan.md

# Protocol Detection Reorganization Plan

## Current Issues

1. **Triple Fragment Handling**: Three separate implementations of fragment buffering:
   - `TlsDetector.detectWithFragments()`
   - `HttpDetector.detectWithFragments()`
   - `ClientHelloParser.handleFragmentedClientHello()`

2. **Overlapping Responsibilities**:
   - Detectors are parsing full protocol details (ALPN, cipher suites, headers)
   - Direct coupling between detectors and protocol parsers
   - Detection and parsing are intermingled

3. **Unclear Boundaries**:
   - Detection should be "what protocol?" but it's doing "parse everything"
   - SNI extraction happens in both detection and SNI handler

## Proposed Reorganization

### 1. Simplify Detection Layer
- Make detectors lightweight - only identify protocol type
- Remove full parsing from detectors
- Return minimal routing info (protocol type, maybe domain)

### 2. Create Shared Fragment Handler
```
ts/protocols/common/
 fragment-handler.ts    # Shared fragment buffering
 types.ts               # Common protocol types
```

### 3. Separate Detection from Parsing
- **Detection**: Quick protocol identification (first few bytes)
- **Parsing**: Full protocol parsing (use existing protocol parsers)
- **Routing**: Extract just routing info (domain/SNI)

### 4. Reorganize Detection Module
```
ts/detection/
 protocol-detector.ts      # Main orchestrator
 detectors/
    quick-detector.ts    # Fast protocol identification
    routing-extractor.ts # Extract routing info only
 utils/
     fragment-manager.ts  # Shared fragment handling
```

### 5. Clear Separation of Concerns
- **Protocols**: Pure protocol knowledge (constants, parsers)
- **Detection**: Protocol identification and minimal routing extraction
- **Handlers**: Full protocol handling (SNI Handler, HTTP Handler, etc.)

## Benefits
- Eliminate duplicate fragment handling code
- Faster detection (less parsing in hot path)
- Clearer boundaries between layers
- Better performance for routing decisions
- Easier to add new protocols

## Implementation Steps

### Phase 1: Create Shared Infrastructure
- [x] Create `ts/protocols/common/` directory
- [x] Implement shared fragment handler
- [x] Define common protocol types

### Phase 2: Simplify Detectors
- [x] Create lightweight protocol identifier
- [x] Create routing info extractor
- [x] Update detectors to use shared components

### Phase 3: Refactor Detection Module
- [x] Update ProtocolDetector to use new architecture (created V2)
- [ ] Remove duplicate fragment handling from old detectors
- [ ] Clean up detector interfaces

### Phase 4: Update Integration Points
- [ ] Update RouteConnectionHandler to use V2
- [ ] Update TlsManager to use V2
- [x] Ensure backward compatibility (both versions exported)

### Phase 5: Testing and Cleanup
- [x] Run all tests (passing)
- [ ] Remove deprecated code after migration
- [ ] Update documentation

## Current Status

The reorganization has been successfully implemented with a V2 architecture that:
- Uses a shared fragment handler to eliminate duplicate code
- Separates quick protocol detection from full parsing
- Provides lightweight routing extraction without full protocol parsing
- Maintains backward compatibility by exporting both V1 and V2 versions

### What's Complete
- All new V2 components are implemented and working
- Tests are passing with the new architecture
- Both old and new versions are available for gradual migration

### Remaining Work
1. **Migration**: Update integration points to use V2 detectors
   - RouteConnectionHandler
   - TlsManager
   - route-helpers.ts

2. **Cleanup**: After migration is verified
   - Remove old detector implementations
   - Remove duplicate fragment handling code
   - Update all imports to use V2

3. **Documentation**: Update docs to reflect new architecture