191 lines
4.3 KiB
Markdown
191 lines
4.3 KiB
Markdown
# 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.
|