SHiNE-server/Dev_Docs/API/05_Technical_Requests_API.md

API для разработчиков: Технические запросы

Этот файл описывает технические запросы, которые не требуют авторизации и нужны для служебной работы клиента с сервером.

Сейчас здесь два метода:

• Ping — keep-alive запрос для поддержания живого WebSocket-соединения;
• GetServerInfo — запрос базовой публичной информации о сервере для выбора узла в децентрализованной сети.

Логика раздела такая:

• Ping нужен для регулярной проверки, что соединение всё ещё живо;
• GetServerInfo нужен до авторизации и до работы с данными, чтобы клиент понял, что сервер доступен, и показал пользователю краткую карточку этого узла.

Ниже сначала описаны назначение методов, затем точные форматы запросов и ответов.

1. Ping

Назначение

Служебный keep-alive запрос.

Клиент может отправлять его периодически, чтобы:

• поддерживать активное WebSocket-соединение;
• понимать, что сервер отвечает;
• при необходимости получать текущее серверное время.

Запрос

{
  "op": "Ping",
  "requestId": "ping-001",
  "payload": {
    "ts": 1774700000123
  }
}

Поле ts в запросе необязательно для логики сервера. Сервер его не валидирует и не использует для принятия решения.

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

{
  "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;
• остальные поля читаются из настроек сервера;
• если значение в конфиге не задано, сервер возвращает пустую строку.

Запрос

{
  "op": "GetServerInfo",
  "requestId": "srv-001",
  "payload": {
  }
}

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

{
  "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-слой и политика доступа.