SHiNE-server/Dev_Docs/API/13_HTTP_Debug_API.md

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:

Authorization: Bearer <token>

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

X-Debug-Token: <token>

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

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

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

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

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

1. GET /debug/ws/clients

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

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

{
  "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

Запрос

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

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

{
  "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.

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

{
  "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.

Запрос

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

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

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

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

Ошибки

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