158 lines
6.7 KiB
Markdown
158 lines
6.7 KiB
Markdown
# API для разработчиков: Технические запросы
|
||
|
||
Этот файл описывает технические запросы, которые не требуют авторизации и нужны для служебной работы клиента с сервером.
|
||
|
||
Сейчас здесь два метода:
|
||
|
||
- `Ping` — keep-alive запрос для поддержания живого WebSocket-соединения;
|
||
- `GetServerInfo` — запрос базовой публичной информации о сервере для выбора узла в децентрализованной сети.
|
||
|
||
Логика раздела такая:
|
||
|
||
- `Ping` нужен для регулярной проверки, что соединение всё ещё живо;
|
||
- `GetServerInfo` нужен до авторизации и до работы с данными, чтобы клиент понял, что сервер доступен, и показал пользователю краткую карточку этого узла.
|
||
|
||
Ниже сначала описаны назначение методов, затем точные форматы запросов и ответов.
|
||
|
||
## 1. `Ping`
|
||
|
||
### Назначение
|
||
|
||
Служебный keep-alive запрос.
|
||
|
||
Клиент может отправлять его периодически, чтобы:
|
||
|
||
- поддерживать активное WebSocket-соединение;
|
||
- понимать, что сервер отвечает;
|
||
- при необходимости получать текущее серверное время.
|
||
|
||
### Запрос
|
||
|
||
```json
|
||
{
|
||
"op": "Ping",
|
||
"requestId": "ping-001",
|
||
"payload": {
|
||
"ts": 1774700000123
|
||
}
|
||
}
|
||
```
|
||
|
||
Поле `ts` в запросе необязательно для логики сервера. Сервер его не валидирует и не использует для принятия решения.
|
||
|
||
### Успешный ответ
|
||
|
||
```json
|
||
{
|
||
"op": "Ping",
|
||
"requestId": "ping-001",
|
||
"status": 200,
|
||
"ok": true,
|
||
"payload": {
|
||
"ts": 1774700000456
|
||
}
|
||
}
|
||
```
|
||
|
||
### Специфические коды ошибок `Ping`
|
||
|
||
- У `Ping` нет специальных прикладных ошибок.
|
||
- Если произойдёт непредвиденная проблема, сервер вернёт общую ошибку из раздела `00`, обычно `500 / INTERNAL_ERROR`.
|
||
|
||
---
|
||
|
||
## 2. `GetServerInfo`
|
||
|
||
### Назначение
|
||
|
||
Запрос публичной информации о сервере.
|
||
|
||
Он нужен клиенту для выбора сервера в децентрализованной сети. По этому запросу клиент может:
|
||
|
||
- проверить, что сервер вообще доступен;
|
||
- показать URL и версию сервера;
|
||
- показать физический регион или адрес размещения;
|
||
- показать описание сервера;
|
||
- показать поле `origin` как комментарий о природе этого узла;
|
||
- показать дополнительную текстовую информацию.
|
||
|
||
Этот запрос доступен без авторизации.
|
||
|
||
### Источник данных
|
||
|
||
- `version` берётся из Gradle build и подставляется в `application.properties`;
|
||
- остальные поля читаются из настроек сервера;
|
||
- если значение в конфиге не задано, сервер возвращает пустую строку.
|
||
|
||
### Запрос
|
||
|
||
```json
|
||
{
|
||
"op": "GetServerInfo",
|
||
"requestId": "srv-001",
|
||
"payload": {
|
||
}
|
||
}
|
||
```
|
||
|
||
### Успешный ответ
|
||
|
||
```json
|
||
{
|
||
"op": "GetServerInfo",
|
||
"requestId": "srv-001",
|
||
"status": 200,
|
||
"ok": true,
|
||
"payload": {
|
||
"url": "wss://node.example.org/ws",
|
||
"version": "1.0",
|
||
"physicalRegion": "Грузия, Тбилиси",
|
||
"description": "Public community SHiNE node",
|
||
"origin": "Community-operated node",
|
||
"extraInfo": "IPv4 + IPv6; test federation enabled"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Поля ответа
|
||
|
||
- `url` — публичный URL сервера.
|
||
- `version` — версия сервера из Gradle build.
|
||
- `physicalRegion` — физический регион или адрес размещения сервера.
|
||
- `description` — человекочитаемое описание сервера.
|
||
- `origin` — комментарий о том, какой это сервер.
|
||
- `extraInfo` — любая дополнительная информация о сервере.
|
||
|
||
### Специфические коды ошибок `GetServerInfo`
|
||
|
||
- У `GetServerInfo` нет специальных прикладных ошибок при штатной работе.
|
||
- Если произойдёт непредвиденная проблема, сервер вернёт общую ошибку из раздела `00`, обычно `500 / INTERNAL_ERROR`.
|
||
|
||
---
|
||
|
||
## 3. Короткое резюме
|
||
|
||
- `Ping` нужен для keep-alive и проверки, что WebSocket-соединение живо.
|
||
- `GetServerInfo` нужен для выбора сервера в сети и показа публичной информации об узле.
|
||
- Оба запроса доступны без авторизации.
|
||
|
||
|
||
## 4. Прямое техническое сообщение в конкретную сессию
|
||
|
||
На текущий момент в публичном JSON API этого документа **нет отдельного RPC** для отправки произвольного технического сообщения в конкретную сессию пользователя (по `sessionId`).
|
||
|
||
Что уже есть в системе:
|
||
|
||
- сервер хранит `sessionId` активной сессии;
|
||
- есть `ListSessions`, чтобы клиент получил список sessionId своего пользователя;
|
||
- у сервера есть внутренний реестр активных WS-подключений по `sessionId`.
|
||
|
||
Чего не хватает для полноценной фичи «direct tech message by sessionId»:
|
||
|
||
1. отдельная API-операция (например, `SendSessionTechMessage`);
|
||
2. правило авторизации (кто имеет право писать в чужую/свою сессию);
|
||
3. унифицированный формат payload и события доставки;
|
||
4. коды ошибок (`SESSION_OFFLINE`, `SESSION_NOT_FOUND`, `FORBIDDEN` и т.п.).
|
||
|
||
Итог: как инфраструктурная база это почти готово, но нужен отдельный RPC-слой и политика доступа.
|