smartproxy/ts/detection/models/interfaces.ts

/**
 * Interface definitions for protocol detection components
 */

import type { IDetectionResult, IDetectionOptions } from './detection-types.js';

/**
 * Interface for protocol detectors
 */
export interface IProtocolDetector {
  /**
   * Detect protocol from buffer data
   * @param buffer The buffer to analyze
   * @param options Detection options
   * @returns Detection result or null if protocol cannot be determined
   */
  detect(buffer: Buffer, options?: IDetectionOptions): IDetectionResult | null;
  
  /**
   * Check if buffer potentially contains this protocol
   * @param buffer The buffer to check
   * @returns True if buffer might contain this protocol
   */
  canHandle(buffer: Buffer): boolean;
  
  /**
   * Get the minimum bytes needed for detection
   */
  getMinimumBytes(): number;
}

/**
 * Interface for connection tracking during fragmented detection
 */
export interface IConnectionTracker {
  /**
   * Connection identifier
   */
  id: string;
  
  /**
   * Accumulated buffer data
   */
  buffer: Buffer;
  
  /**
   * Timestamp of first data
   */
  startTime: number;
  
  /**
   * Current detection state
   */
  state: 'detecting' | 'complete' | 'failed';
  
  /**
   * Partial detection result (if any)
   */
  partialResult?: Partial<IDetectionResult>;
}

/**
 * Interface for buffer accumulator (handles fragmented data)
 */
export interface IBufferAccumulator {
  /**
   * Add data to accumulator
   */
  append(data: Buffer): void;
  
  /**
   * Get accumulated buffer
   */
  getBuffer(): Buffer;
  
  /**
   * Get buffer length
   */
  length(): number;
  
  /**
   * Clear accumulated data
   */
  clear(): void;
  
  /**
   * Check if accumulator has enough data
   */
  hasMinimumBytes(minBytes: number): boolean;
}

/**
 * Detection events
 */
export interface IDetectionEvents {
  /**
   * Emitted when protocol is successfully detected
   */
  detected: (result: IDetectionResult) => void;
  
  /**
   * Emitted when detection fails
   */
  failed: (error: Error) => void;
  
  /**
   * Emitted when detection times out
   */
  timeout: () => void;
  
  /**
   * Emitted when more data is needed
   */
  needMoreData: (bytesNeeded: number) => void;
}