# API для разработчиков: HTTP debug endpoints

Этот файл описывает отдельный HTTP debug API сервера. Он не использует WebSocket-конверт `op/requestId/payload` и включается только настройкой:

- `debug.tempApi.enabled=true`

Источник истины:

- `src/main/java/server/debug/DebugApiConfigurator.java`
- `src/main/java/server/debug/*Servlet.java`

Если `.debug-token` отсутствует или пуст, endpoints возвращают `503 / DEBUG_DISABLED`.

## Авторизация

Для большинства debug endpoints используется Bearer token из `.debug-token`:

```http
Authorization: Bearer <token>
```

Для `POST /debug/ws/ui-reload-all` поддерживается заголовок:

```http
X-Debug-Token: <token>
```

При неверном токене сервер возвращает `401 / UNAUTHORIZED`.

## Формат успешного HTTP-ответа

```json
{
  "ok": true,
  "payload": {
  }
}
```

## Формат HTTP-ошибки

```json
{
  "ok": false,
  "code": "BAD_JSON",
  "message": "Тело запроса должно быть JSON"
}
```

## 1. `GET /debug/ws/clients`

Возвращает список активных WebSocket-клиентов.

### Успешный ответ

```json
{
  "ok": true,
  "payload": {
    "count": 1,
    "clients": [
      {
        "sessionId": "SESSION_ID",
        "login": "alice",
        "authStatus": 2,
        "wsOpen": true,
        "remoteAddress": "127.0.0.1",
        "ip": "127.0.0.1",
        "userAgent": "Mozilla/5.0 ...",
        "clientInfoFromClient": "...",
        "clientInfoFromRequest": "...",
        "userLanguage": "ru",
        "sessionCreatedAtMs": 1774700000123
      }
    ]
  }
}
```

## 2. `POST /debug/ws/connect`

Запускает debug-сценарий соединения двух активных WS-сессий и отправляет им события:

- `DebugConnectPrepareResponder`
- `DebugConnectStartInitiator`

### Запрос

```json
{
  "initiatorSessionId": "SESSION_ID_1",
  "responderSessionId": "SESSION_ID_2",
  "clearDebugLog": true
}
```

### Успешный ответ

```json
{
  "ok": true,
  "payload": {
    "runId": "dbg-...",
    "callId": "debug-call-...",
    "accepted": true,
    "initiatorSessionId": "SESSION_ID_1",
    "responderSessionId": "SESSION_ID_2",
    "initiatorLogin": "alice",
    "responderLogin": "bob",
    "mode": "cross-login"
  }
}
```

### Ошибки

- `400 / BAD_JSON` — тело запроса не JSON.
- `400 / BAD_FIELDS` — не заполнены sessionId или переданы одинаковые sessionId.
- `404 / INITIATOR_NOT_FOUND` — сессия инициатора не найдена или неактивна.
- `404 / RESPONDER_NOT_FOUND` — сессия получателя не найдена или неактивна.

## 3. `GET /debug/ws/logs`

Возвращает tail debug-логов из `DebugRunLogBuffer`.

### Query-параметры

- `limit` — количество записей.
- `runId` — фильтр по runId.

### Успешный ответ

```json
{
  "ok": true,
  "payload": {
    "count": 1,
    "limit": 100,
    "runIdFilter": "ui-run-1",
    "logs": [
      {
        "ts": 1774700000123,
        "level": "info",
        "runId": "ui-run-1",
        "source": "debug-connect",
        "sessionId": "SESSION_ID",
        "login": "alice",
        "message": "opened channels tab",
        "details": "{}"
      }
    ]
  }
}
```

## 4. `POST /debug/ws/ui-reload-all`

Рассылает активным UI-сессиям debug-событие на reload.

### Запрос

```json
{
  "reason": "manual_debug_api",
  "reloadAfterMs": 700
}
```

Если `reason` не передан или пустой, сервер использует `manual_debug_api`. `reloadAfterMs` ограничивается диапазоном `100..15000`.

### Успешный ответ

```json
{
  "ok": true,
  "payload": {
    "accepted": true,
    "reason": "manual_debug_api",
    "reloadAfterMs": 700,
    "issuedAtMs": 1774700000123,
    "totalConnections": 2,
    "sentCount": 2,
    "skippedCount": 0
  }
}
```

### Ошибки

- `400 / BAD_JSON` — тело запроса не JSON.