solver-sdk/docs/PING_PONG.md

SDK для интеграции с Code Solver Backend API

# Механизм Ping/Pong для WebSocket

Для поддержания активных WebSocket соединений и проверки их состояния SDK использует механизм ping/pong.

## Что такое ping/pong?

Ping/pong - это механизм отправки специальных сообщений между клиентом и сервером для проверки активности соединения. 
Клиент периодически отправляет сообщение "ping", на которое сервер должен ответить сообщением "pong".
Если ответа нет в течение определенного времени, соединение считается разорванным.

## Как это работает в SDK?

SDK автоматически настраивает и управляет ping/pong механизмом, когда вы используете следующие высокоуровневые методы:

```javascript
// Подключение к WebSocket пространствам имен
await sdk.connect(); // Подключается ко всем пространствам имен

// Или более специфичные подключения
await sdk.reasoning.connectWebSocket(reasoningId);
await sdk.dependencies.connectWebSocket(projectId);
await sdk.projects.connectWebSocket();
```

### Настройка ping/pong

По умолчанию SDK использует следующие настройки:
- Интервал ping: 25 секунд
- Таймаут ожидания pong: 60 секунд

Эти настройки можно изменить при инициализации SDK:

```javascript
const sdk = new CodeSolverSDK({
  baseURL: 'https://api.example.com',
  apiKey: 'your-api-key',
  websocket: {
    pingInterval: 30000,  // 30 секунд
    pingTimeout: 90000    // 90 секунд
  }
});
```

### Преимущества автоматического ping/pong

1. **Обнаружение разрывов соединения**: Если сервер не отвечает на ping, SDK обнаружит разрыв соединения.
2. **Предотвращение тайм-аутов**: Регулярные ping/pong сообщения поддерживают соединение активным и предотвращают тайм-ауты на промежуточных серверах и брандмауэрах.
3. **Автоматическое переподключение**: SDK может автоматически переподключаться при обнаружении разрыва соединения.

### События ping/pong

SDK предоставляет события для отслеживания состояния ping/pong:

```javascript
// Настройка обработчиков для всех WebSocket соединений
sdk.on('connection_timeout', async (data) => {
  console.warn(`Соединение с ${data.namespace} истекло по тайм-ауту`);
  // Автоматически SDK попытается переподключиться
});
```

## Рекомендуемые практики

1. **Используйте высокоуровневые методы подключения**: Самый простой способ обеспечить надежное соединение - использовать встроенные высокоуровневые методы SDK.

2. **Включите автоматическое переподключение**: При инициализации SDK установите параметры:
   ```javascript
   const sdk = new CodeSolverSDK({
     baseURL: 'https://api.example.com',
     apiKey: 'your-api-key',
     websocket: {
       reconnect: true,
       reconnectAttempts: 5,
       reconnectDelay: 2000
     }
   });
   ```

3. **Обрабатывайте события тайм-аута**: Регистрируйте обработчики событий, чтобы знать, когда соединение было потеряно.

4. **Правильно завершайте соединения**: Перед закрытием приложения вызывайте метод для отключения:
   ```javascript
   // Отключение перед закрытием приложения
   await sdk.disconnect();
   ```

## Пример обработки тайм-аутов

```javascript
// Инициализация SDK
const sdk = new CodeSolverSDK({
  baseURL: 'https://api.example.com',
  apiKey: 'your-api-key'
});

// Подключение к WebSocket
await sdk.connect();

// Обработка события тайм-аута
sdk.on('connection_timeout', handleConnectionTimeout);

// Функция обработки тайм-аута
async function handleConnectionTimeout(data) {
  console.warn(`Соединение с ${data.namespace} прервано по тайм-ауту`);
  
  // Вы можете добавить свою логику обработки
  // Например, уведомить пользователя или попытаться переподключиться
}

// Перед закрытием приложения
// Корректно отключаемся
await sdk.disconnect();
```