@dynamicu/chromedebug-mcp 2.2.0

package/src/capture/error-handling-types.ts

@@ -0,0 +1,360 @@
+/**
+ * Chrome Pilot Error Handling System - Type Definitions
+ * Architecture designed collaboratively with Second Opinion Consultant
+ *
+ * APPROVED ARCHITECTURE - No modifications without team review
+ */
+
+// System Requirements
+export const SYSTEM_REQUIREMENTS = {
+  maxDataLossTime: 30000, // 30 seconds max data loss
+  maxRetainedInteractions: 100, // Memory limit
+  notificationThrottleMs: 5000, // User experience
+  maxRetryAttempts: 3,
+  backupRetentionDays: 7,
+  recoverabilityLevel: 'GUARANTEED' as const
+} as const;
+
+// Data Protection Tiers
+export interface DataProtectionTier {
+  maxLoss: number;
+  includes: string[];
+  storage: 'PERSISTENT_BACKUP' | 'REDUNDANT_STORAGE' | 'SINGLE_STORAGE';
+}
+
+export const DATA_PROTECTION_TIERS = {
+  CRITICAL_DATA: {
+    maxLoss: 0,
+    includes: ['session_metadata', 'user_authentication'],
+    storage: 'PERSISTENT_BACKUP'
+  } as DataProtectionTier,
+
+  HIGH_VALUE_DATA: {
+    maxLoss: 30000,
+    includes: ['user_interactions', 'form_data'],
+    storage: 'REDUNDANT_STORAGE'
+  } as DataProtectionTier,
+
+  RECOVERABLE_DATA: {
+    maxLoss: 300000,
+    includes: ['performance_metrics', 'debug_logs'],
+    storage: 'SINGLE_STORAGE'
+  } as DataProtectionTier
+} as const;
+
+// Enhanced Screen Interaction Format
+export interface ScreenInteraction {
+  type: 'click' | 'scroll' | 'keypress' | 'mousemove';
+  timestamp: number;
+  x?: number;
+  y?: number;
+
+  // Enhanced fields for error recovery
+  element_html?: string;
+  component_data?: string;
+  event_handlers?: string;
+  element_state?: string;
+  performance_metrics?: string;
+
+  // Error tracking
+  id?: string;
+  sessionId: string;
+  retryCount?: number;
+  compressionApplied?: boolean;
+}
+
+// Error State Management
+export interface ErrorDetails {
+  type: 'NETWORK_FAILURE' | 'SERVER_ERROR' | 'STORAGE_FAILURE' | 'BROWSER_CRASH' | 'NOTIFICATION_FAILURE';
+  message: string;
+  timestamp: number;
+  retryCount: number;
+  stackTrace?: string;
+  context?: Record<string, any>;
+}
+
+export interface ErrorState {
+  failedSaveCount: number;
+  lastNotificationTime: number;
+  retainedInteractions: ScreenInteraction[];
+  lastError: ErrorDetails;
+  circuitBreakerState: 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+  id?: string;
+  sessionId: string;
+}
+
+// Backup/Recovery Format
+export interface SessionInfo {
+  sessionId: string;
+  startTime: number;
+  userId?: string;
+  pageUrl: string;
+  userAgent: string;
+}
+
+export interface BackupData {
+  sessionId: string;
+  interactions: ScreenInteraction[];
+  timestamp: number;
+  sessionData: SessionInfo;
+  retryCount: number;
+  compressionRatio?: number;
+  backupType: 'AUTOMATIC' | 'MANUAL' | 'EMERGENCY';
+}
+
+// Notification System
+export interface NotificationButton {
+  text: string;
+  action: 'RETRY' | 'DISCARD' | 'VIEW_DETAILS' | 'DOWNLOAD_BACKUP';
+  primary?: boolean;
+}
+
+export interface NotificationConfig {
+  throttleMs: number;
+  maxRetainedInteractions: number;
+  retryThreshold: number;
+  buttons: NotificationButton[];
+  title: string;
+  message: string;
+  priority: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+}
+
+// Storage Architecture
+export interface StorageTier {
+  api: 'chrome.storage.local' | 'IndexedDB' | 'sessionStorage';
+  maxSize: string;
+  data: string[];
+  backup?: string;
+}
+
+export const STORAGE_ARCHITECTURE = {
+  critical: {
+    api: 'chrome.storage.local',
+    maxSize: '1MB',
+    data: ['sessionId', 'userAuth', 'recoveryTokens'],
+    backup: 'IndexedDB mirror'
+  } as StorageTier,
+
+  highValue: {
+    api: 'IndexedDB',
+    maxSize: '50MB',
+    data: ['interactions', 'formData', 'elementStates'],
+    backup: 'chrome.storage.local (compressed)'
+  } as StorageTier,
+
+  recoverable: {
+    api: 'IndexedDB',
+    maxSize: 'Unlimited (with cleanup)',
+    data: ['performance', 'debugLogs', 'analytics'],
+    backup: 'None (acceptable loss)'
+  } as StorageTier
+} as const;
+
+// Communication Protocol
+export interface ServerUploadPayload {
+  sessionId: string;
+  interactions: ScreenInteraction[];
+  metadata: SessionInfo;
+}
+
+export interface ServerUploadConfig {
+  endpoint: string;
+  method: 'POST';
+  headers: Record<string, string>;
+  payload: ServerUploadPayload;
+  timeout: number;
+  retryStrategy: 'exponentialBackoff';
+  circuitBreaker: 'enabled';
+  fallbackAction: 'STORE_LOCAL_BACKUP';
+}
+
+// Internal Messages
+export type InternalMessageType = 'SAVE_FAILURE' | 'RECOVERY_REQUEST' | 'BACKUP_COMPLETE';
+
+export interface InternalMessage<T = any> {
+  type: InternalMessageType;
+  from: 'background' | 'contentScript' | 'errorHandler';
+  to: 'background' | 'contentScript' | 'errorHandler';
+  data: T;
+  timestamp: number;
+}
+
+// Circuit Breaker Pattern
+export interface CircuitBreakerConfig {
+  failureThreshold: number;
+  resetTimeout: number;
+  states: ['CLOSED', 'OPEN', 'HALF_OPEN'];
+}
+
+export const CIRCUIT_BREAKER_CONFIG: CircuitBreakerConfig = {
+  failureThreshold: 3,
+  resetTimeout: 30000,
+  states: ['CLOSED', 'OPEN', 'HALF_OPEN']
+} as const;
+
+// State Machine
+export type ErrorHandlingState =
+  | 'NORMAL_OPERATION'
+  | 'ERROR_DETECTED'
+  | 'BACKUP_MODE'
+  | 'RECOVERY_ATTEMPT'
+  | 'CRITICAL_FAILURE'
+  | 'MANUAL_RECOVERY';
+
+export type ErrorHandlingEvent =
+  | 'SAVE_FAILURE'
+  | 'NETWORK_ERROR'
+  | 'RETRY_SUCCESS'
+  | 'RETRY_FAILURE'
+  | 'MAX_RETRIES_EXCEEDED'
+  | 'BACKUP_SUCCESS'
+  | 'BACKUP_FAILURE'
+  | 'NETWORK_RESTORED'
+  | 'RECOVERY_SUCCESS'
+  | 'RECOVERY_FAILURE'
+  | 'USER_INTERVENTION'
+  | 'SYSTEM_RESET';
+
+export interface StateTransition {
+  from: ErrorHandlingState;
+  event: ErrorHandlingEvent;
+  to: ErrorHandlingState;
+  actions: string[];
+}
+
+export interface StateMachineConfig {
+  initialState: ErrorHandlingState;
+  states: Record<ErrorHandlingState, {
+    on: Partial<Record<ErrorHandlingEvent, ErrorHandlingState>>;
+    actions: string[];
+  }>;
+}
+
+// IndexedDB Schema
+export interface IndexedDBIndex {
+  name: string;
+  keyPath: string;
+  unique?: boolean;
+}
+
+export interface IndexedDBStore {
+  keyPath: string;
+  autoIncrement?: boolean;
+  indexes: IndexedDBIndex[];
+  data: string;
+}
+
+export interface IndexedDBSchema {
+  database: string;
+  version: number;
+  stores: Record<string, IndexedDBStore>;
+}
+
+// Compression Configuration
+export interface CompressionConfig {
+  algorithm: 'gzip';
+  threshold: number;
+  targets: string[];
+  ratio: number;
+}
+
+export const COMPRESSION_CONFIG: CompressionConfig = {
+  algorithm: 'gzip',
+  threshold: 1024,
+  targets: ['element_html', 'component_data', 'element_state'],
+  ratio: 0.3
+} as const;
+
+// Export complete configuration objects
+export const ERROR_HANDLING_STATE_MACHINE: StateMachineConfig = {
+  initialState: 'NORMAL_OPERATION',
+
+  states: {
+    NORMAL_OPERATION: {
+      on: {
+        SAVE_FAILURE: 'ERROR_DETECTED',
+        NETWORK_ERROR: 'BACKUP_MODE'
+      },
+      actions: ['processInteractions', 'uploadToServer']
+    },
+
+    ERROR_DETECTED: {
+      on: {
+        RETRY_SUCCESS: 'NORMAL_OPERATION',
+        RETRY_FAILURE: 'BACKUP_MODE',
+        MAX_RETRIES_EXCEEDED: 'CRITICAL_FAILURE'
+      },
+      actions: ['incrementRetryCount', 'exponentialBackoff', 'retryUpload']
+    },
+
+    BACKUP_MODE: {
+      on: {
+        BACKUP_SUCCESS: 'RECOVERY_ATTEMPT',
+        BACKUP_FAILURE: 'CRITICAL_FAILURE',
+        NETWORK_RESTORED: 'RECOVERY_ATTEMPT'
+      },
+      actions: ['storeLocalBackup', 'notifyUser', 'monitorNetwork']
+    },
+
+    RECOVERY_ATTEMPT: {
+      on: {
+        RECOVERY_SUCCESS: 'NORMAL_OPERATION',
+        RECOVERY_FAILURE: 'BACKUP_MODE'
+      },
+      actions: ['uploadBackedData', 'clearLocalBackup']
+    },
+
+    CRITICAL_FAILURE: {
+      on: {
+        USER_INTERVENTION: 'MANUAL_RECOVERY',
+        SYSTEM_RESET: 'NORMAL_OPERATION'
+      },
+      actions: ['persistCriticalData', 'notifyUserCritical', 'logError']
+    },
+
+    MANUAL_RECOVERY: {
+      on: {
+        RECOVERY_SUCCESS: 'NORMAL_OPERATION',
+        SYSTEM_RESET: 'NORMAL_OPERATION'
+      },
+      actions: ['processUserInput', 'attemptManualRecovery']
+    }
+  }
+} as const;
+
+export const INDEXEDDB_SCHEMA: IndexedDBSchema = {
+  database: 'ChromePilotErrorRecovery',
+  version: 1,
+  stores: {
+    interactions: {
+      keyPath: 'id',
+      autoIncrement: true,
+      indexes: [
+        { name: 'sessionId', keyPath: 'sessionId' },
+        { name: 'timestamp', keyPath: 'timestamp' },
+        { name: 'type', keyPath: 'type' }
+      ],
+      data: 'ScreenInteraction[]'
+    },
+
+    sessionBackups: {
+      keyPath: 'sessionId',
+      indexes: [
+        { name: 'timestamp', keyPath: 'timestamp' },
+        { name: 'retryCount', keyPath: 'retryCount' }
+      ],
+      data: 'BackupData'
+    },
+
+    errorStates: {
+      keyPath: 'id',
+      autoIncrement: true,
+      indexes: [
+        { name: 'sessionId', keyPath: 'sessionId' },
+        { name: 'errorType', keyPath: 'errorType' },
+        { name: 'timestamp', keyPath: 'timestamp' }
+      ],
+      data: 'ErrorState'
+    }
+  }
+} as const;