Документировать API и сервис агента-кодера

2026-05-24 08:04:44 +03:00
parent aa2644d812
commit 4b371e142d
53 changed files with 4317 additions and 18 deletions
@@ -0,0 +1,190 @@
+# 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.