112 lines
3.8 KiB
Markdown
112 lines
3.8 KiB
Markdown
# 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 |