solver-sdk 2.5.0 → 2.6.1

package/docs/ERROR_HANDLING.md

@@ -1,173 +1,613 @@
-# Обработка ошибок в SDK
+# Обработка ошибок v2.5.0
 
-SDK предоставляет различные механизмы обработки ошибок для HTTP запросов и WebSocket соединений.
+Полная документация по обработке ошибок в AI Solver SDK v2.5.0.
+
+## Философия "Fail Fast"
+
+SDK v2.5.0 следует принципу "fail fast" - ошибки возникают сразу при обнаружении проблем, без тихих fallback'ов.
 
 ## Обработка HTTP ошибок
 
 ### Использование try/catch
 
-Рекомендуемый способ обработки ошибок - использование конструкции `try/catch`:
+Рекомендуемый способ обработки ошибок:
 
 ```javascript
+import { CodeSolverSDK } from '@ai-solver/sdk';
+
 try {
-  // Выполнение запроса
-  const projects = await sdk.projects.getAllProjects();
-  console.log('Получено проектов:', projects.length);
+  const projects = await sdk.projects.getAll();
+  console.log('✅ Получено проектов:', projects.total);
 } catch (error) {
-  console.error('Ошибка при получении проектов:', error);
+  console.error('❌ Ошибка:', error.message);
   
-  // Можно проверить тип ошибки
+  // Проверка типа ошибки
   if (error.status === 401) {
-    console.error('Ошибка авторизации. Проверьте API ключ.');
+    console.error('🔑 Ошибка аутентификации');
   } else if (error.status === 404) {
-    console.error('Ресурс не найден.');
+    console.error('🔍 Ресурс не найден');
   } else if (error.code === 'NETWORK_ERROR') {
-    console.error('Проблема с сетевым соединением.');
+    console.error('🌐 Проблема сети');
   }
 }
 ```
 
-### Глобальный обработчик ошибок
+### Структура ошибок
 
-Можно установить глобальный обработчик ошибок SDK:
+SDK v2.5.0 возвращает стандартизированные ошибки:
 
 ```javascript
-// Установка глобального обработчика
-CodeSolverSDK.setErrorHandler((error) => {
-  console.error('Глобальная ошибка SDK:', error);
-  // Отправка информации об ошибке в мониторинг
-  sendToMonitoring(error);
-});
-
-// После этого необработанные ошибки SDK будут передаваться в этот обработчик
+// Пример объекта ошибки
+{
+  name: 'APIError',
+  message: 'Project not found',
+  status: 404,
+  code: 'PROJECT_NOT_FOUND',
+  endpoint: '/api/v1/projects/123',
+  method: 'GET',
+  timestamp: '2025-06-28T12:00:00Z',
+  requestId: 'req_abc123'
+}
 ```
 
-## Обработка ошибок WebSocket
+## Обработка WebSocket ошибок
 
 ### Обработка событий ошибок
 
-SDK позволяет подписаться на события ошибок для различных API:
-
 ```javascript
-// Для индексации проектов
-sdk.projects.on('error', (error) => {
-  console.error('Ошибка индексации:', error);
+// Projects WebSocket ошибки
+await sdk.projects.connectWebSocket();
+
+sdk.projects.onIndexingError((error) => {
+  console.error('❌ Indexing error:', error.message);
+  console.error('📁 Project:', error.projectId);
+  console.error('📄 File:', error.fileName);
 });
 
-// Для рассуждений
-sdk.reasoning.on('error', (error) => {
-  console.error('Ошибка рассуждения:', error);
+// Reasoning WebSocket ошибки
+await sdk.reasoning.connectWebSocket();
+
+sdk.reasoning.onReasoningError((error) => {
+  console.error('❌ Reasoning error:', error.message);
+  console.error('🆔 Reasoning ID:', error.reasoningId);
 });
-```
 
-### Обработка ошибок соединения
+// Chat WebSocket ошибки
+await sdk.chat.connectWebSocket();
 
-При использовании высокоуровневых методов подключения можно обрабатывать ошибки соединения:
+sdk.chat.on('error', (error) => {
+  console.error('❌ Chat error:', error.message);
+});
+```
+
+### Обработка ошибок подключения
 
 ```javascript
 try {
-  // Попытка подключения к WebSocket
-  await sdk.connect();
-  console.log('Подключение установлено');
+  await sdk.projects.connectWebSocket();
+  console.log('✅ Projects WebSocket connected');
 } catch (error) {
-  console.error('Ошибка подключения:', error);
+  console.error('❌ WebSocket connection failed:', error.message);
+  
+  if (error.code === 'WS_CONNECTION_REFUSED') {
+    console.error('🔌 Server unavailable');
+  } else if (error.code === 'WS_AUTH_FAILED') {
+    console.error('🔑 Authentication failed');
+  }
 }
 ```
 
-### Автоматическое переподключение
+## Диагностика ошибок
 
-SDK поддерживает автоматическое переподключение в случае разрыва соединения:
+### API диагностика
 
 ```javascript
-const sdk = new CodeSolverSDK({
-  baseURL: 'https://api.example.com',
-  apiKey: 'your-api-key',
-  websocket: {
-    reconnect: true,                 // Включить автоматическое переподключение
-    reconnectAttempts: 5,            // Максимальное число попыток
-    reconnectDelay: 3000             // Задержка между попытками (мс)
+// Полная диагностика всех endpoints
+const diagnostics = await sdk.diagnoseAPI();
+console.log('📊 API Diagnostics:', diagnostics);
+
+/* Пример результата:
+{
+  '/api/v1/projects': { 
+    status: 200, 
+    success: true, 
+    responseTime: 120 
+  },
+  '/api/v1/reasoning': { 
+    status: 401, 
+    success: false, 
+    error: 'Invalid API key' 
+  },
+  '/api/v1/chat': { 
+    status: 500, 
+    success: false, 
+    error: 'Internal server error' 
   }
-});
+}
+*/
+```
+
+### WebSocket диагностика
+
+```javascript
+// Диагностика WebSocket соединений
+const wsStatus = await sdk.diagnoseWebSocket();
+console.log('🔌 WebSocket status:', wsStatus);
+
+/* Пример результата:
+{
+  projects: { 
+    connected: true, 
+    url: 'ws://localhost:3000/projects' 
+  },
+  reasoning: { 
+    connected: false, 
+    error: 'Connection timeout' 
+  },
+  chat: { 
+    connected: true, 
+    latency: 45 
+  }
+}
+*/
 ```
 
-## Типичные ошибки и их решения
+## Типы ошибок
+
+### HTTP ошибки
 
-### Ошибки подключения
+#### 400 Bad Request
 
-| Код ошибки | Описание | Решение |
-|------------|----------|---------|
-| `NETWORK_ERROR` | Ошибка сети | Проверьте подключение к Интернету |
-| `ETIMEDOUT` | Таймаут соединения | Увеличьте значение `timeout` в настройках SDK |
-| `CONNECTION_REFUSED` | Соединение отклонено | Проверьте правильность URL и доступность сервера |
-| `CERT_ERROR` | Ошибка сертификата | Используйте параметр `rejectUnauthorized: false` для локальной разработки |
+```javascript
+{
+  status: 400,
+  code: 'VALIDATION_ERROR',
+  message: 'Invalid project data',
+  details: {
+    field: 'name',
+    issue: 'Name is required'
+  }
+}
+```
 
-### Ошибки аутентификации
+**Решение:** Проверьте корректность входных данных.
 
-| Код ошибки | Описание | Решение |
-|------------|----------|---------|
-| `401 Unauthorized` | Неверный API ключ | Проверьте правильность API ключа |
-| `403 Forbidden` | Недостаточно прав | Проверьте права доступа для API ключа |
-| `AUTH_EXPIRED` | Срок действия токена истек | Обновите API ключ |
+#### 401 Unauthorized
 
-### Ошибки индексации
+```javascript
+{
+  status: 401,
+  code: 'AUTH_INVALID_KEY',
+  message: 'Invalid or missing API key'
+}
+```
 
-| Код ошибки | Описание | Решение |
-|------------|----------|---------|
-| `PROJECT_NOT_FOUND` | Проект не найден | Проверьте ID проекта |
-| `INDEXING_IN_PROGRESS` | Индексация уже выполняется | Дождитесь завершения текущей индексации |
-| `INDEXING_ERROR` | Ошибка во время индексации | Проверьте лог ошибок на сервере |
+**Решение:** Проверьте API ключ в настройках SDK.
 
-## Пример комплексной обработки ошибок
+#### 403 Forbidden
 
 ```javascript
-async function initializeSDK() {
+{
+  status: 403,
+  code: 'AUTH_INSUFFICIENT_SCOPE',
+  message: 'Insufficient permissions',
+  required_scope: 'projects:write'
+}
+```
+
+**Решение:** Используйте API ключ с необходимыми правами.
+
+#### 404 Not Found
+
+```javascript
+{
+  status: 404,
+  code: 'PROJECT_NOT_FOUND',
+  message: 'Project with ID "123" not found'
+}
+```
+
+**Решение:** Проверьте правильность ID ресурса.
+
+#### 429 Too Many Requests
+
+```javascript
+{
+  status: 429,
+  code: 'RATE_LIMIT_EXCEEDED',
+  message: 'Rate limit exceeded',
+  retry_after: 60
+}
+```
+
+**Решение:** Подождите указанное время или используйте Production ключ.
+
+#### 500 Internal Server Error
+
+```javascript
+{
+  status: 500,
+  code: 'INTERNAL_ERROR',
+  message: 'Internal server error',
+  incident_id: 'inc_abc123'
+}
+```
+
+**Решение:** Сообщите о проблеме с указанием incident_id.
+
+### WebSocket ошибки
+
+#### WS_CONNECTION_REFUSED
+
+```javascript
+{
+  code: 'WS_CONNECTION_REFUSED',
+  message: 'WebSocket connection refused',
+  namespace: 'projects'
+}
+```
+
+**Решение:** Проверьте доступность сервера.
+
+#### WS_AUTH_FAILED
+
+```javascript
+{
+  code: 'WS_AUTH_FAILED',
+  message: 'WebSocket authentication failed',
+  namespace: 'reasoning'
+}
+```
+
+**Решение:** Проверьте API ключ.
+
+#### WS_TIMEOUT
+
+```javascript
+{
+  code: 'WS_TIMEOUT',
+  message: 'WebSocket connection timeout',
+  timeout: 30000
+}
+```
+
+**Решение:** Увеличьте timeout или проверьте сеть.
+
+### Network ошибки
+
+#### NETWORK_ERROR
+
+```javascript
+{
+  code: 'NETWORK_ERROR',
+  message: 'Network request failed',
+  cause: 'ECONNREFUSED'
+}
+```
+
+**Решение:** Проверьте подключение к интернету и доступность сервера.
+
+#### TIMEOUT_ERROR
+
+```javascript
+{
+  code: 'TIMEOUT_ERROR',
+  message: 'Request timeout after 30000ms',
+  timeout: 30000
+}
+```
+
+**Решение:** Увеличьте timeout в настройках SDK.
+
+## Стратегии обработки ошибок
+
+### Retry стратегия
+
+```javascript
+async function retryableRequest(operation, maxRetries = 3) {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      console.warn(`⚠️ Attempt ${attempt} failed:`, error.message);
+      
+      // Не повторяем для клиентских ошибок
+      if (error.status >= 400 && error.status < 500) {
+        throw error;
+      }
+      
+      // Последняя попытка
+      if (attempt === maxRetries) {
+        throw error;
+      }
+      
+      // Экспоненциальная задержка
+      const delay = Math.pow(2, attempt) * 1000;
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+}
+
+// Использование
+try {
+  const projects = await retryableRequest(() => sdk.projects.getAll());
+} catch (error) {
+  console.error('❌ All retries failed:', error.message);
+}
+```
+
+### Circuit Breaker
+
+```javascript
+class CircuitBreaker {
+  constructor(threshold = 5, timeout = 60000) {
+    this.threshold = threshold;
+    this.timeout = timeout;
+    this.failures = 0;
+    this.state = 'CLOSED'; // CLOSED, OPEN, HALF_OPEN
+    this.nextAttempt = Date.now();
+  }
+  
+  async execute(operation) {
+    if (this.state === 'OPEN') {
+      if (Date.now() < this.nextAttempt) {
+        throw new Error('Circuit breaker is OPEN');
+      }
+      this.state = 'HALF_OPEN';
+    }
+    
+    try {
+      const result = await operation();
+      this.onSuccess();
+      return result;
+    } catch (error) {
+      this.onFailure();
+      throw error;
+    }
+  }
+  
+  onSuccess() {
+    this.failures = 0;
+    this.state = 'CLOSED';
+  }
+  
+  onFailure() {
+    this.failures++;
+    if (this.failures >= this.threshold) {
+      this.state = 'OPEN';
+      this.nextAttempt = Date.now() + this.timeout;
+    }
+  }
+}
+
+// Использование
+const breaker = new CircuitBreaker();
+
+try {
+  const result = await breaker.execute(() => sdk.chat.send(messages));
+} catch (error) {
+  console.error('❌ Circuit breaker error:', error.message);
+}
+```
+
+### Graceful degradation
+
+```javascript
+async function robustProjectCreation(projectData) {
   try {
-    // Проверка доступности API
-    const isHealthy = await sdk.checkHealth();
-    
-    if (!isHealthy) {
-      console.error('API недоступен, пробуем резервный сервер');
-      // Создаем новый экземпляр SDK с резервным URL
-      return new CodeSolverSDK({
-        baseURL: 'https://backup-api.example.com',
-        apiKey: 'your-api-key'
-      });
+    // Основной путь
+    const project = await sdk.projects.create(projectData);
+    console.log('✅ Project created:', project.id);
+    
+    // Запуск индексации
+    try {
+      await sdk.projects.startIndexing(project.id);
+      console.log('✅ Indexing started');
+    } catch (indexError) {
+      console.warn('⚠️ Indexing failed, but project created:', indexError.message);
     }
     
-    // Подключение к WebSocket
-    await sdk.connect();
-    console.log('SDK успешно инициализирован');
+    return project;
     
-    return sdk;
   } catch (error) {
-    console.error('Ошибка при инициализации SDK:', error);
+    console.error('❌ Project creation failed:', error.message);
     
-    // Логирование ошибки для отладки
-    logError('SDK_INIT_ERROR', error);
+    // Fallback: сохраняем локально
+    const localProject = {
+      id: `local_${Date.now()}`,
+      name: projectData.name,
+      path: projectData.path,
+      local: true
+    };
     
-    // В зависимости от ошибки предпринимаем разные действия
-    if (error.code === 'CONNECTION_ERROR') {
-      console.warn('Продолжаем работу без WebSocket подключения');
-      return sdk; // Возвращаем SDK, но без WebSocket функциональности
-    }
+    localStorage.setItem(`project_${localProject.id}`, JSON.stringify(localProject));
+    console.log('💾 Project saved locally:', localProject.id);
     
-    // Для критических ошибок выбрасываем исключение
-    throw new Error(`Не удалось инициализировать SDK: ${error.message}`);
+    return localProject;
   }
 }
+```
+
+## Мониторинг ошибок
+
+### Логирование ошибок
+
+```javascript
+function logError(error, context = {}) {
+  const errorLog = {
+    timestamp: new Date().toISOString(),
+    error: {
+      name: error.name,
+      message: error.message,
+      status: error.status,
+      code: error.code,
+      stack: error.stack
+    },
+    context: {
+      ...context,
+      userAgent: navigator.userAgent,
+      url: window.location.href,
+      userId: getCurrentUserId()
+    }
+  };
+  
+  // Отправка в систему мониторинга
+  sendToMonitoring(errorLog);
+  
+  // Локальное логирование
+  console.error('🚨 Error logged:', errorLog);
+}
 
 // Использование
-const sdk = await initializeSDK().catch(error => {
-  console.error('Критическая ошибка:', error);
-  // Показываем пользователю сообщение об ошибке
-  showErrorMessage('Не удалось подключиться к серверу');
+try {
+  await sdk.reasoning.start(reasoningId);
+} catch (error) {
+  logError(error, {
+    operation: 'reasoning_start',
+    reasoningId: reasoningId,
+    projectId: projectId
+  });
+}
+```
+
+### Метрики ошибок
+
+```javascript
+class ErrorMetrics {
+  constructor() {
+    this.errors = new Map();
+  }
+  
+  record(error) {
+    const key = `${error.code || 'UNKNOWN'}_${error.status || 0}`;
+    const count = this.errors.get(key) || 0;
+    this.errors.set(key, count + 1);
+  }
   
-  // Возвращаем отключенную версию SDK или null
-  return null;
+  getReport() {
+    const report = Array.from(this.errors.entries())
+      .map(([error, count]) => ({ error, count }))
+      .sort((a, b) => b.count - a.count);
+    
+    return {
+      totalErrors: Array.from(this.errors.values()).reduce((a, b) => a + b, 0),
+      topErrors: report.slice(0, 5),
+      allErrors: report
+    };
+  }
+}
+
+// Глобальные метрики
+const errorMetrics = new ErrorMetrics();
+
+// Автоматическая регистрация ошибок
+window.addEventListener('unhandledrejection', (event) => {
+  errorMetrics.record(event.reason);
 });
+```
+
+## Пример комплексной обработки
+
+```javascript
+async function initializeAIWorkflow(projectPath, query) {
+  const sdk = CodeSolverSDK.create({
+    baseURL: 'http://localhost:3000',
+    apiKey: process.env.AI_SOLVER_API_KEY,
+    autoConnect: false
+  });
+  
+  try {
+    // 1. Диагностика API
+    console.log('🔍 Diagnosing API...');
+    const apiStatus = await sdk.diagnoseAPI();
+    
+    const healthyEndpoints = Object.entries(apiStatus)
+      .filter(([_, status]) => status.success)
+      .map(([endpoint]) => endpoint);
+    
+    if (healthyEndpoints.length === 0) {
+      throw new Error('No healthy endpoints available');
+    }
+    
+    console.log('✅ Healthy endpoints:', healthyEndpoints);
+    
+    // 2. Создание проекта
+    console.log('📁 Creating project...');
+    const project = await retryableRequest(() => 
+      sdk.projects.create({
+        name: 'AI Analysis Project',
+        path: projectPath
+      })
+    );
+    
+    // 3. Индексация с WebSocket
+    console.log('📊 Starting indexing...');
+    await sdk.projects.connectWebSocket();
+    
+    let indexingComplete = false;
+    sdk.projects.onIndexingComplete(() => {
+      indexingComplete = true;
+      console.log('✅ Indexing completed');
+      sdk.projects.disconnectWebSocket();
+    });
+    
+    sdk.projects.onIndexingError((error) => {
+      console.error('❌ Indexing failed:', error.message);
+      sdk.projects.disconnectWebSocket();
+    });
+    
+    await sdk.projects.startIndexing(project.id);
+    
+    // Ожидание завершения индексации
+    while (!indexingComplete) {
+      await new Promise(resolve => setTimeout(resolve, 1000));
+    }
+    
+    // 4. AI Reasoning
+    console.log('🧠 Starting reasoning...');
+    await sdk.reasoning.connectWebSocket();
+    
+    const reasoning = await sdk.reasoning.create({
+      projectId: project.id,
+      query: query
+    });
+    
+    await sdk.reasoning.start(reasoning.id);
+    
+    return {
+      project,
+      reasoning,
+      success: true
+    };
+    
+  } catch (error) {
+    console.error('❌ Workflow failed:', error.message);
+    
+    // Очистка ресурсов
+    try {
+      await sdk.projects.disconnectWebSocket();
+      await sdk.reasoning.disconnectWebSocket();
+    } catch (cleanupError) {
+      console.warn('⚠️ Cleanup warning:', cleanupError.message);
+    }
+    
+    // Регистрация ошибки
+    logError(error, {
+      workflow: 'ai_analysis',
+      projectPath,
+      query
+    });
+    
+    return {
+      error: error.message,
+      success: false
+    };
+  }
+}
+```
+
+---
 
-if (sdk) {
-  // Продолжаем работу с SDK
-} else {
-  // Работаем в режиме ограниченной функциональности
-} 
+**Документация обработки ошибок для SDK v2.5.0**  
+**Принцип:** Fail Fast, явные ошибки, надежная диагностика  
+**Обновлено:** 28 июня 2025