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

• Create ts/protocols/common/ directory
• Implement shared fragment handler
• Define common protocol types

Phase 2: Simplify Detectors

• Create lightweight protocol identifier
• Create routing info extractor
• Update detectors to use shared components

Phase 3: Refactor Detection Module

• 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
• Ensure backward compatibility (both versions exported)

Phase 5: Testing and Cleanup

• 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