SHA256
Перенести документацию в docs и добавить социальный граф
This commit is contained in:
AidarKC
@@ -0,0 +1,140 @@
|
||||
# API для разработчиков: Общий формат запросов и ответов
|
||||
|
||||
Этот файл описывает не конкретные операции, а общий wire-контракт всего API сервера.
|
||||
|
||||
Здесь зафиксировано:
|
||||
|
||||
- как выглядит любой запрос;
|
||||
- как выглядит любой успешный ответ;
|
||||
- как выглядит любой ответ с ошибкой;
|
||||
- какие поля являются обязательными для всех операций;
|
||||
- как клиент должен интерпретировать `status`, `ok` и `payload`.
|
||||
|
||||
Логика простая: сначала клиент и сервер договариваются о едином формате конверта, и только потом в остальных документах уже описываются конкретные методы и их поля.
|
||||
|
||||
## 1. Общий формат запроса
|
||||
|
||||
Все запросы по WebSocket используют один и тот же JSON-конверт:
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "OperationName",
|
||||
"requestId": "req-001",
|
||||
"payload": {
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Поля
|
||||
|
||||
- `op` — имя операции.
|
||||
- `requestId` — клиентский идентификатор запроса.
|
||||
- `payload` — объект параметров операции.
|
||||
|
||||
---
|
||||
|
||||
## 2. Общий формат успешного ответа
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "OperationName",
|
||||
"requestId": "req-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Общий формат ответа с ошибкой
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "OperationName",
|
||||
"requestId": "req-001",
|
||||
"status": 400,
|
||||
"ok": false,
|
||||
"error": "BAD_REQUEST",
|
||||
"message": "Human readable description",
|
||||
"payload": {
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Обязательные правила
|
||||
|
||||
- Сервер возвращает `op` в каждом ответе.
|
||||
- Сервер возвращает `requestId` в каждом ответе без изменений.
|
||||
- Сервер возвращает `status` в каждом ответе.
|
||||
- Сервер возвращает `ok` в каждом ответе.
|
||||
- Сервер всегда возвращает `payload` как объект.
|
||||
- Даже при отсутствии данных сервер возвращает `payload: {}`.
|
||||
- `ok` находится на верхнем уровне ответа, а не внутри `payload`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Правило интерпретации
|
||||
|
||||
Источник истины — `status`.
|
||||
|
||||
- если `status` в диапазоне `200..299`, то ответ успешный и `ok` должен быть `true`;
|
||||
- если `status` вне диапазона `200..299`, то ответ ошибочный и `ok` должен быть `false`.
|
||||
|
||||
Запрещённые состояния:
|
||||
|
||||
- `status = 200` и `ok = false`;
|
||||
- `status = 400` и `ok = true`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Общие правила формата
|
||||
|
||||
- Все строки подписи и challenge собираются в UTF-8.
|
||||
- Временные метки передаются как Unix time в миллисекундах.
|
||||
- Бинарные поля передаются строками Base64.
|
||||
- При ошибке `error` — это машинный код причины.
|
||||
- При ошибке `message` — человекочитаемое описание причины.
|
||||
|
||||
---
|
||||
|
||||
## 7. Общие коды ошибок
|
||||
|
||||
Ниже перечислены коды ошибок, которые не привязаны к одной конкретной операции и могут встречаться в разных местах API.
|
||||
|
||||
- `400 / EMPTY_JSON` — клиент отправил пустое или полностью отсутствующее JSON-сообщение.
|
||||
- `400 / NO_OP` — в корневом объекте не передано поле `op`.
|
||||
- `400 / UNKNOWN_OP` — сервер не знает такую операцию.
|
||||
- `400 / NO_PAYLOAD` — в корневом объекте отсутствует `payload`.
|
||||
- `400 / BAD_PAYLOAD` — `payload` передан, но это не JSON-объект.
|
||||
- `400 / BAD_REQUEST_FORMAT` — JSON-конверт формально валиден, но поля операции не удалось распарсить в ожидаемый формат.
|
||||
- `500 / INTERNAL_HANDLER_ERROR` — в handler конкретной операции случилась непредвиденная серверная ошибка.
|
||||
- `500 / INTERNAL_ERROR` — произошла внутренняя ошибка на уровне общего JSON-процессора или другого серверного слоя.
|
||||
|
||||
Общее правило для dev/test этапа:
|
||||
|
||||
- `message` в таких ошибках должен быть коротким, но полезным;
|
||||
- по возможности сервер добавляет тип исключения и краткую деталь причины;
|
||||
- это сделано для упрощения интеграционных тестов и отладки;
|
||||
- позже для production этот уровень детализации может быть уменьшен.
|
||||
|
||||
---
|
||||
|
||||
## 8. Источник истины по списку операций
|
||||
|
||||
Фактический список публичных WebSocket-операций берётся из:
|
||||
|
||||
- `shine-server-net-protocol/src/main/java/server/logic/ws_protocol/JSON/JsonHandlerRegistry.java`.
|
||||
|
||||
Если операция зарегистрирована в `HANDLERS` и `REQUEST_TYPES`, она считается доступной через JSON/WebSocket API. Общий актуальный индекс таких операций поддерживается в `Dev_Docs/API/09_Operations_Index.md`.
|
||||
|
||||
---
|
||||
|
||||
## 9. Короткое резюме
|
||||
|
||||
- Запросы всегда идут как `op + requestId + payload`.
|
||||
- Ответы всегда идут как `op + requestId + status + ok + payload`.
|
||||
- Ошибки всегда возвращают `ok: false`, `error`, `message`, `payload: {}`.
|
||||
@@ -0,0 +1,201 @@
|
||||
# API для разработчиков: Регистрация пользователя
|
||||
|
||||
Этот файл описывает раздел API, связанный с проверкой наличия пользователя на сервере и dev/test операциями.
|
||||
|
||||
Сейчас здесь три метода:
|
||||
|
||||
- `AddUser` — операция отключена (регистрация только через Solana);
|
||||
- `GetUser` — временная серверная проверка существования пользователя и чтение его базовых данных;
|
||||
- `SearchUsers` — dev/test поиск логинов по префиксу.
|
||||
|
||||
Регистрация выполняется через Solana (`shine_users`). Сервер при входе может лениво импортировать пользователя из Solana PDA в локальную БД, если записи ещё нет.
|
||||
|
||||
## Статус документа
|
||||
|
||||
Это временная глава API.
|
||||
|
||||
Текущая регистрация пользователя и текущая проверка, существует пользователь или нет, пока реализованы как серверные dev/test операции. В будущем и регистрация, и проверка identity должны идти напрямую через Solana.
|
||||
|
||||
---
|
||||
|
||||
## 1. Операция `AddUser`
|
||||
|
||||
### Назначение
|
||||
|
||||
Операция отключена. Используется только как явный ответ клиентам старых версий.
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "AddUser",
|
||||
"requestId": "reg-001",
|
||||
"payload": {
|
||||
"login": "anya",
|
||||
"blockchainName": "anya-001",
|
||||
"solanaKey": "BASE64_32_PUBLIC_KEY",
|
||||
"blockchainKey": "BASE64_32_PUBLIC_KEY",
|
||||
"clientKey": "BASE64_32_PUBLIC_KEY",
|
||||
"bchLimit": 1000000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Пример ответа
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "AddUser",
|
||||
"requestId": "reg-001",
|
||||
"status": 410,
|
||||
"ok": false,
|
||||
"error": "ADD_USER_DISABLED",
|
||||
"message": "Серверная регистрация AddUser отключена. Используйте регистрацию через Solana.",
|
||||
"payload": {
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Специфические коды ошибок `AddUser`
|
||||
|
||||
- `410 / ADD_USER_DISABLED` — серверная регистрация отключена, используйте Solana-first flow.
|
||||
|
||||
---
|
||||
|
||||
## 2. Операция `GetUser`
|
||||
|
||||
### Назначение
|
||||
|
||||
Временная серверная проверка, существует пользователь или нет.
|
||||
|
||||
Важно:
|
||||
|
||||
- это server-side existence-check;
|
||||
- если пользователя нет в локальной БД, сервер сразу пытается lazy-import из Solana PDA;
|
||||
- поэтому `GetUser` можно использовать как актуальный способ получить `clientKey` и базовые поля пользователя перед E2EE DM.
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "GetUser",
|
||||
"requestId": "user-001",
|
||||
"payload": {
|
||||
"login": "anya"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ: пользователь существует
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "GetUser",
|
||||
"requestId": "user-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"exists": true,
|
||||
"login": "Anya",
|
||||
"blockchainName": "anya-001",
|
||||
"solanaKey": "BASE64_32_PUBLIC_KEY",
|
||||
"blockchainKey": "BASE64_32_PUBLIC_KEY",
|
||||
"clientKey": "BASE64_32_PUBLIC_KEY",
|
||||
"serverLastGlobalNumber": 128,
|
||||
"serverLastGlobalHash": "4f...ab",
|
||||
"serverBlockchainSizeBytes": 45212,
|
||||
"serverBlockchainSizeLimitBytes": 100000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Дополнительные серверные поля в `GetUser`:
|
||||
|
||||
- `serverLastGlobalNumber` — номер последнего блока в пользовательском блокчейне на сервере;
|
||||
- `serverLastGlobalHash` — hash последнего блока (hex-строка 64 символа);
|
||||
- `serverBlockchainSizeBytes` — текущий размер пользовательского блокчейна на сервере в байтах;
|
||||
- `serverBlockchainSizeLimitBytes` — текущий лимит размера блокчейна на сервере в байтах;
|
||||
|
||||
### Успешный ответ: пользователя нет
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "GetUser",
|
||||
"requestId": "user-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"exists": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Пример ошибки
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "GetUser",
|
||||
"requestId": "user-001",
|
||||
"status": 400,
|
||||
"ok": false,
|
||||
"error": "BAD_FIELDS",
|
||||
"message": "Некорректные поля: login",
|
||||
"payload": {
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Специфические коды ошибок `GetUser`
|
||||
|
||||
- `400 / BAD_FIELDS` — не передан или пуст `login`.
|
||||
- `501 / DB_ERROR` — ошибка БД при поиске пользователя.
|
||||
- `500 / INTERNAL_ERROR` — непредвиденная внутренняя ошибка сервера.
|
||||
|
||||
---
|
||||
|
||||
## 3. Операция `SearchUsers`
|
||||
|
||||
### Назначение
|
||||
|
||||
Поиск пользователей по префиксу логина. Операция зарегистрирована в серверном API и используется как вспомогательная dev/test операция.
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "SearchUsers",
|
||||
"requestId": "search-001",
|
||||
"payload": {
|
||||
"prefix": "an"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "SearchUsers",
|
||||
"requestId": "search-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"logins": ["anya", "andrey"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Специфические коды ошибок `SearchUsers`
|
||||
|
||||
- `400 / BAD_FIELDS` — некорректный или пустой `prefix`.
|
||||
- `501 / DB_ERROR` — ошибка БД при поиске.
|
||||
- `500 / INTERNAL_ERROR` — непредвиденная внутренняя ошибка сервера.
|
||||
|
||||
---
|
||||
|
||||
## 4. Короткое резюме
|
||||
|
||||
- `AddUser` — отключен (`410 / ADD_USER_DISABLED`).
|
||||
- `GetUser` — проверка существования пользователя на сервере.
|
||||
- `SearchUsers` — временный поиск пользователей по префиксу.
|
||||
- Регистрация выполняется только через Solana.
|
||||
@@ -0,0 +1,341 @@
|
||||
# API для разработчиков: Авторизация
|
||||
|
||||
Этот файл описывает именно этапы авторизации клиента, то есть как создать новую сессию и как войти в уже существующую.
|
||||
|
||||
Здесь четыре базовых метода обычной авторизации:
|
||||
|
||||
- `AuthChallenge`
|
||||
- `CreateAuthSession`
|
||||
- `SessionChallenge`
|
||||
- `SessionLogin`
|
||||
|
||||
Логика раздела такая:
|
||||
|
||||
- сначала клиент либо начинает создание новой сессии через `clientKey`;
|
||||
- либо начинает вход в уже созданную сессию через `sessionKey`;
|
||||
- сервер на первом шаге выдаёт challenge/nonce;
|
||||
- на втором шаге клиент присылает подписанный ответ;
|
||||
- сервер сверяет актуальные публичные ключи и только потом проверяет подпись.
|
||||
|
||||
Новые поля этого раздела:
|
||||
|
||||
- `sessionType` — числовой код типа сессии;
|
||||
- `clientPlatform` — свободная строка платформы клиента.
|
||||
|
||||
Текущие поддерживаемые коды `sessionType`:
|
||||
|
||||
- `1` — обычный клиент;
|
||||
- `50` — кошелёк;
|
||||
- `100` — homeserver.
|
||||
|
||||
Правило проверки `sessionType`:
|
||||
|
||||
1. если в `Solana PDA` нет записи для `sessionKey`, сервер принимает `sessionType`, присланный клиентом;
|
||||
2. если запись в `PDA` есть, `sessionType` в запросе должен совпадать с `session_type` из `PDA`;
|
||||
3. при несовпадении сервер возвращает `460 / SESSION_TYPE_MISMATCH`.
|
||||
|
||||
Ниже в документе сначала описан сценарий, а потом зафиксированы точные форматы запросов и ответов.
|
||||
|
||||
Отдельно появился новый серверный сценарий pairing через доверенный homeserver/ESP. Он не заменяет обычный вход и описан в:
|
||||
|
||||
- `Dev_Docs/Протоколы/ESP_Pairing_и_режимы_подключения.md`
|
||||
|
||||
Кратко:
|
||||
|
||||
- `AuthChallenge/CreateAuthSession` и `SessionChallenge/SessionLogin` остаются каноническими потоками обычной авторизации;
|
||||
- pairing через ESP идёт отдельными `op` и только подготавливает безопасное добавление новой сессии;
|
||||
- решение об одобрении pairing принимает любая уже авторизованная доверенная сессия пользователя.
|
||||
|
||||
## 1. Поток авторизации
|
||||
|
||||
Поддерживаются два сценария:
|
||||
|
||||
1. Создание новой сессии:
|
||||
`AuthChallenge` -> `CreateAuthSession`
|
||||
2. Вход в существующую сессию:
|
||||
`SessionChallenge` -> `SessionLogin`
|
||||
|
||||
`clientKey` используется для создания новой сессии.
|
||||
|
||||
`sessionKey` используется для входа в уже созданную сессию.
|
||||
|
||||
`sessionKey` передаётся и хранится целиком одной строкой, например:
|
||||
|
||||
```text
|
||||
ed25519/BASE64_PUBLIC_KEY
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. `AuthChallenge`
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "AuthChallenge",
|
||||
"requestId": "auth-001",
|
||||
"payload": {
|
||||
"login": "alice"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "AuthChallenge",
|
||||
"requestId": "auth-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"authNonce": "8f2f0f71-0b1c-4ab2-8f5d-0bc5d6f6aa11"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Специфические коды ошибок `AuthChallenge`
|
||||
|
||||
- `400 / EMPTY_LOGIN` — пустой `login`.
|
||||
- `400 / ALREADY_AUTHED` — по текущему соединению уже выполнена авторизация.
|
||||
- `422 / UNKNOWN_USER` — пользователь с таким `login` не найден.
|
||||
- `501 / SOLANA_IMPORT_FAILED` — сервер не смог проверить/импортировать пользователя из Solana при lazy-import.
|
||||
- `500 / INTERNAL_ERROR` — непредвиденная внутренняя ошибка сервера, если появится вне штатного сценария.
|
||||
|
||||
---
|
||||
|
||||
## 3. `CreateAuthSession`
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "CreateAuthSession",
|
||||
"requestId": "create-001",
|
||||
"payload": {
|
||||
"login": "alice",
|
||||
"sessionKey": "ed25519/BASE64_PUBLIC_KEY",
|
||||
"storagePwd": "BASE64_OR_APP_SPECIFIC_SECRET",
|
||||
"timeMs": 1774600000123,
|
||||
"authNonce": "nonce",
|
||||
"clientKey": "BASE64_DEVICE_PUBLIC_KEY",
|
||||
"signatureB64": "BASE64_SIGNATURE",
|
||||
"sessionType": 1,
|
||||
"clientPlatform": "Web",
|
||||
"clientInfo": "Android 15; Pixel 9"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Строка для подписи
|
||||
|
||||
```text
|
||||
AUTH_CREATE_SESSION:{login}:{sessionKey}:{storagePwd}:{timeMs}:{authNonce}
|
||||
```
|
||||
|
||||
### Дополнительная проверка ключа
|
||||
|
||||
Перед проверкой подписи сервер должен:
|
||||
|
||||
1. взять актуальный `solana_users.client_key`;
|
||||
2. сравнить его с `payload.clientKey`;
|
||||
3. только потом проверять подпись.
|
||||
|
||||
Если `clientKey` не совпадает, сервер возвращает ошибку `DEVICE_KEY_NOT_ACTUAL`.
|
||||
|
||||
На будущее:
|
||||
|
||||
- для ротации `client_key` желательно добавить перепроверку через Solana.
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "CreateAuthSession",
|
||||
"requestId": "create-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"sessionId": "sess_7c5e5c4b"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Специфические коды ошибок `CreateAuthSession`
|
||||
|
||||
- `400 / NO_STEP1_CONTEXT` — для данного соединения не был корректно выполнен `AuthChallenge`.
|
||||
- `400 / EMPTY_LOGIN` — пустой `login`.
|
||||
- `400 / LOGIN_MISMATCH` — `login` не совпадает с тем, для кого был выдан `authNonce`.
|
||||
- `501 / DB_ERROR_USER_LOOKUP` — ошибка БД при повторном чтении пользователя.
|
||||
- `422 / USER_NOT_FOUND` — пользователь не найден.
|
||||
- `501 / NO_LOGIN` — у пользователя на сервере не заполнен `login`.
|
||||
- `400 / EMPTY_STORAGE_PWD` — пустой `storagePwd`.
|
||||
- `400 / EMPTY_SESSION_KEY` — пустой `sessionKey`.
|
||||
- `422 / UNSUPPORTED_KEY_ALGORITHM` — префикс алгоритма в `sessionKey` или `clientKey` не поддерживается текущим сервером.
|
||||
- `400 / BAD_BASE64` — неверный Base64 в `sessionKey`, `clientKey` или `signatureB64`.
|
||||
- `400 / EMPTY_SIGNATURE` — пустая подпись.
|
||||
- `400 / TIME_SKEW` — время клиента отличается от серверного больше допустимого окна.
|
||||
- `400 / NO_DEVICE_KEY` — у пользователя в БД отсутствует `clientKey`.
|
||||
- `400 / EMPTY_AUTH_NONCE` — пустой `authNonce`.
|
||||
- `400 / AUTH_NONCE_MISMATCH` — `authNonce` не соответствует значению из `AuthChallenge`.
|
||||
- `400 / EMPTY_DEVICE_KEY` — в запросе не передан `clientKey`.
|
||||
- `422 / DEVICE_KEY_NOT_ACTUAL` — `clientKey` не совпадает с актуальной версией на сервере.
|
||||
- `422 / BAD_SIGNATURE` — подпись не прошла проверку.
|
||||
- `460 / SESSION_TYPE_MISMATCH` — `sessionType` не совпадает с типом сессии, уже опубликованным для этого `sessionKey` в Solana PDA.
|
||||
- `501 / SESSION_TYPE_PDA_CHECK_FAILED` — сервер не смог проверить `sessionType` по Solana PDA.
|
||||
- `501 / DB_ERROR_SESSION_CREATE` — ошибка БД при создании записи активной сессии.
|
||||
- `500 / INTERNAL_ERROR` — непредвиденная внутренняя ошибка сервера.
|
||||
|
||||
---
|
||||
|
||||
## 4. `SessionChallenge`
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "SessionChallenge",
|
||||
"requestId": "sch-001",
|
||||
"payload": {
|
||||
"sessionId": "sess_7c5e5c4b"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "SessionChallenge",
|
||||
"requestId": "sch-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"nonce": "0e5bb0f4-c7d8-4efb-b44d-bf31a6126c66"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Специфические коды ошибок `SessionChallenge`
|
||||
|
||||
- `400 / EMPTY_SESSION_ID` — пустой `sessionId`.
|
||||
- `501 / DB_ERROR` — ошибка БД при чтении сессии.
|
||||
- `422 / SESSION_NOT_FOUND` — сессия не найдена.
|
||||
- `500 / INTERNAL_ERROR` — непредвиденная внутренняя ошибка сервера.
|
||||
|
||||
---
|
||||
|
||||
## 5. `SessionLogin`
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "SessionLogin",
|
||||
"requestId": "slogin-001",
|
||||
"payload": {
|
||||
"sessionId": "sess_7c5e5c4b",
|
||||
"sessionKey": "ed25519/BASE64_PUBLIC_KEY",
|
||||
"timeMs": 1774600010456,
|
||||
"signatureB64": "BASE64_SIGNATURE",
|
||||
"sessionType": 1,
|
||||
"clientPlatform": "Web",
|
||||
"clientInfo": "Android 15; Pixel 9"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Строка для подписи
|
||||
|
||||
```text
|
||||
SESSION_LOGIN:{sessionId}:{timeMs}:{nonce}
|
||||
```
|
||||
|
||||
### Дополнительная проверка ключа
|
||||
|
||||
Перед проверкой подписи сервер должен:
|
||||
|
||||
1. взять `active_sessions.session_key`;
|
||||
2. сравнить его с `payload.sessionKey`;
|
||||
3. только потом проверять подпись.
|
||||
|
||||
Если ключ не совпадает, сервер возвращает ошибку `SESSION_KEY_NOT_ACTUAL`.
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "SessionLogin",
|
||||
"requestId": "slogin-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"storagePwd": "BASE64_OR_APP_SPECIFIC_SECRET"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Специфические коды ошибок `SessionLogin`
|
||||
|
||||
- `400 / EMPTY_SESSION_ID` — пустой `sessionId`.
|
||||
- `400 / NO_CHALLENGE` — перед `SessionLogin` не был успешно выполнен `SessionChallenge` либо nonce уже истёк.
|
||||
- `400 / SESSION_ID_MISMATCH` — nonce был выдан для другого `sessionId`.
|
||||
- `400 / TIME_SKEW` — время клиента отличается от серверного больше допустимого окна.
|
||||
- `400 / EMPTY_SIGNATURE` — пустая подпись.
|
||||
- `400 / EMPTY_SESSION_KEY` — пустой `sessionKey`.
|
||||
- `501 / DB_ERROR` — ошибка БД при чтении сессии.
|
||||
- `422 / SESSION_NOT_FOUND` — сессия не найдена.
|
||||
- `501 / NO_SESSION_KEY` — у сессии отсутствует `session_key`.
|
||||
- `422 / SESSION_KEY_NOT_ACTUAL` — переданный `sessionKey` не совпадает с актуальной версией на сервере.
|
||||
- `422 / UNSUPPORTED_KEY_ALGORITHM` — префикс алгоритма в `sessionKey` не поддерживается текущим сервером.
|
||||
- `400 / BAD_BASE64` — неверный Base64 в `sessionKey` или `signatureB64`.
|
||||
- `422 / BAD_SIGNATURE` — подпись не прошла проверку.
|
||||
- `460 / SESSION_TYPE_MISMATCH` — `sessionType` не совпадает с типом сессии, уже опубликованным для этого `sessionKey` в Solana PDA.
|
||||
- `501 / SESSION_TYPE_PDA_CHECK_FAILED` — сервер не смог проверить `sessionType` по Solana PDA.
|
||||
- `501 / DB_ERROR_USER_LOOKUP` — ошибка БД при чтении пользователя для этой сессии.
|
||||
- `422 / USER_NOT_FOUND_FOR_SESSION` — пользователь, которому принадлежит сессия, не найден.
|
||||
- `500 / INTERNAL_ERROR` — непредвиденная внутренняя ошибка сервера.
|
||||
|
||||
---
|
||||
|
||||
## 6. Pairing через homeserver/ESP
|
||||
|
||||
Новые `op`, относящиеся к этому сценарию:
|
||||
|
||||
- `GetTrustedDeviceLoginSettings`
|
||||
- `UpsertTrustedDeviceLoginSettings`
|
||||
- `StartTrustedDeviceLogin`
|
||||
- `ListTrustedDeviceLoginRequests`
|
||||
- `ApproveTrustedDeviceLogin`
|
||||
- `RejectTrustedDeviceLogin`
|
||||
- `CancelTrustedDeviceLogin`
|
||||
- `GetTrustedDeviceLoginStatus`
|
||||
|
||||
В этом потоке:
|
||||
|
||||
- новое устройство не владеет `clientKey` и не проходит обычный `CreateAuthSession`;
|
||||
- пароль проверяется сервером только как фильтр;
|
||||
- решение об одобрении принимает уже авторизованная доверенная сессия пользователя;
|
||||
- сервер не расшифровывает `encryptedPayload` и не становится источником приватных ключей.
|
||||
|
||||
Точные форматы этих операций см. в `03_Session_Management_API.md` и в протокольном документе:
|
||||
|
||||
- `Dev_Docs/Протоколы/ESP_Pairing_и_режимы_подключения.md`
|
||||
|
||||
---
|
||||
|
||||
## 6. Пример ошибки
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "SessionLogin",
|
||||
"requestId": "slogin-001",
|
||||
"status": 403,
|
||||
"ok": false,
|
||||
"error": "SESSION_KEY_NOT_ACTUAL",
|
||||
"message": "session_key не соответствует актуальной версии",
|
||||
"payload": {
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,485 @@
|
||||
# API для разработчиков: Управление сессиями
|
||||
|
||||
Этот файл описывает методы, которые используются уже после успешной авторизации пользователя в сессию.
|
||||
|
||||
Здесь два метода:
|
||||
|
||||
- `ListSessions` — получить список активных сессий пользователя;
|
||||
- `CloseActiveSession` — закрыть одну из активных сессий.
|
||||
|
||||
Дополнительно в этом же слое управления сессиями появился сценарий pairing через доверенную уже авторизованную сессию пользователя:
|
||||
|
||||
- `GetTrustedDeviceLoginSettings`
|
||||
- `UpsertTrustedDeviceLoginSettings`
|
||||
- `ListTrustedDeviceLoginRequests`
|
||||
- `ApproveTrustedDeviceLogin`
|
||||
- `RejectTrustedDeviceLogin`
|
||||
- `CancelTrustedDeviceLogin`
|
||||
|
||||
Анонимное новое устройство работает с двумя связанными операциями:
|
||||
|
||||
- `StartTrustedDeviceLogin`
|
||||
- `GetTrustedDeviceLoginStatus`
|
||||
|
||||
Логика раздела такая:
|
||||
|
||||
- сначала пользователь проходит `SessionLogin`;
|
||||
- после этого сервер считает соединение авторизованным;
|
||||
- уже в этом состоянии клиент может читать список сессий и управлять ими.
|
||||
|
||||
То есть это не этап создания или входа в сессию, а этап последующего контроля уже существующих активных сессий.
|
||||
|
||||
## 1. `ListSessions`
|
||||
|
||||
Доступно только после успешного `SessionLogin`.
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "ListSessions",
|
||||
"requestId": "list-001",
|
||||
"payload": {
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "ListSessions",
|
||||
"requestId": "list-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"sessions": [
|
||||
{
|
||||
"sessionId": "sess_7c5e5c4b",
|
||||
"sessionType": 1,
|
||||
"clientPlatform": "Web",
|
||||
"onlineOnThisServer": true,
|
||||
"clientInfoFromClient": "Android 15; Pixel 9",
|
||||
"clientInfoFromRequest": "UA=Java-http-client/17.0.18; remote=127.0.0.1",
|
||||
"geo": "RU/Moscow",
|
||||
"lastAuthenticatedAtMs": 1774600010500
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Специфические коды ошибок `ListSessions`
|
||||
|
||||
- `422 / NOT_AUTHENTICATED` — запрос доступен только после успешного `SessionLogin`.
|
||||
- `501 / DB_ERROR_LIST_SESSIONS` — ошибка БД при чтении списка активных сессий.
|
||||
- `500 / INTERNAL_ERROR` — непредвиденная внутренняя ошибка сервера.
|
||||
|
||||
### Поля одной сессии в `ListSessions`
|
||||
|
||||
- `sessionId` — идентификатор активной сессии;
|
||||
- `sessionType` — числовой код типа сессии:
|
||||
- `1` — клиент;
|
||||
- `50` — кошелёк;
|
||||
- `100` — homeserver;
|
||||
- `clientPlatform` — строка платформы, как её прислал клиент;
|
||||
- `onlineOnThisServer` — `true`, если эта сессия сейчас держит живое WebSocket-подключение именно к данному серверу;
|
||||
- `clientInfoFromClient` — краткая строка клиента;
|
||||
- `clientInfoFromRequest` — строка, собранная сервером из запроса;
|
||||
- `geo` — страна/город или fallback-строка;
|
||||
- `lastAuthenticatedAtMs` — время последней успешной авторизации этой сессии.
|
||||
|
||||
---
|
||||
|
||||
## 2. `CloseActiveSession`
|
||||
|
||||
Доступно только после успешного `SessionLogin`.
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "CloseActiveSession",
|
||||
"requestId": "close-001",
|
||||
"payload": {
|
||||
"sessionId": "sess_7c5e5c4b"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "CloseActiveSession",
|
||||
"requestId": "close-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Специфические коды ошибок `CloseActiveSession`
|
||||
|
||||
- `422 / NOT_AUTHENTICATED` — запрос доступен только после успешного `SessionLogin`.
|
||||
- `400 / NO_SESSION_TO_CLOSE` — сервер не смог определить, какую сессию нужно закрыть.
|
||||
- `501 / DB_ERROR` — ошибка БД при поиске сессии или её удалении.
|
||||
- `422 / SESSION_NOT_FOUND` — целевая сессия не найдена.
|
||||
- `422 / SESSION_OF_ANOTHER_USER` — нельзя закрывать сессию другого пользователя.
|
||||
- `500 / INTERNAL_ERROR` — непредвиденная внутренняя ошибка сервера.
|
||||
|
||||
---
|
||||
|
||||
## 3. Пример ошибки
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "CloseActiveSession",
|
||||
"requestId": "close-001",
|
||||
"status": 403,
|
||||
"ok": false,
|
||||
"error": "NOT_AUTHENTICATED",
|
||||
"message": "Операция доступна только для авторизованных пользователей",
|
||||
"payload": {
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## 4. Формат `sessionId`
|
||||
|
||||
Текущее серверное значение `sessionId` генерируется как:
|
||||
|
||||
- случайные **32 байта** (`SecureRandom`),
|
||||
- кодирование в **стандартный Base64 RFC 4648** (алфавит `A-Z a-z 0-9 + /`),
|
||||
- **без padding** `=`.
|
||||
|
||||
Практически это строка длиной около **43 символов** (для 32 байт без `=`).
|
||||
|
||||
Пример реального формата:
|
||||
|
||||
```
|
||||
K9v3nQ4u8jYk0a2p7cD4mLx1zR0sT5wV6bN8eH3fQ1M
|
||||
```
|
||||
|
||||
Важно: это **не человеко-читаемое имя**, а непрозрачный идентификатор.
|
||||
Нужно передавать его как есть, без нормализации регистра и без URL-экранирования внутри JSON.
|
||||
|
||||
---
|
||||
|
||||
## 5. TrustedDeviceLogin через доверенную сессию
|
||||
|
||||
Этот блок относится к сценарию добавления новой сессии через доверенное устройство пользователя.
|
||||
|
||||
### 5.1. `GetTrustedDeviceLoginSettings`
|
||||
|
||||
Доступно для любой уже авторизованной доверенной сессии пользователя.
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "GetTrustedDeviceLoginSettings",
|
||||
"requestId": "trusted-login-get-001",
|
||||
"payload": {
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "GetTrustedDeviceLoginSettings",
|
||||
"requestId": "trusted-login-get-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"enabled": true,
|
||||
"hasPassword": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Если отдельной записи настроек на сервере ещё нет, сервер считает состояние по умолчанию таким:
|
||||
|
||||
- `enabled = true`
|
||||
- `hasPassword = false`
|
||||
|
||||
### Ошибки
|
||||
|
||||
- `463 / PAIRING_REQUIRES_AUTH_SESSION` — операция вызвана без уже авторизованной доверенной сессии пользователя.
|
||||
|
||||
### 5.2. `UpsertTrustedDeviceLoginSettings`
|
||||
|
||||
Доступно для любой уже авторизованной доверенной сессии пользователя.
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "UpsertTrustedDeviceLoginSettings",
|
||||
"requestId": "esp-set-001",
|
||||
"payload": {
|
||||
"enabled": true,
|
||||
"passwordHash": "sha256$0123abcd..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Если вход через доверенное устройство должен работать **без доп. пароля**, клиент включает его с пустым `passwordHash`.
|
||||
|
||||
Если `enabled = false`, сервер автоматически удаляет пароль и запрещает вход через другое устройство.
|
||||
|
||||
Формат непустого `passwordHash`:
|
||||
|
||||
```text
|
||||
sha256$<hex( SHA-256("shine-pairing|" + lower(login.trim()) + "|" + password) )>
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "UpsertTrustedDeviceLoginSettings",
|
||||
"requestId": "esp-set-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"enabled": true,
|
||||
"hasPassword": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Ошибки
|
||||
|
||||
- `463 / PAIRING_REQUIRES_AUTH_SESSION` — операция вызвана без уже авторизованной доверенной сессии пользователя.
|
||||
|
||||
### 5.3. `StartTrustedDeviceLogin`
|
||||
|
||||
Эта операция доступна без уже существующей пользовательской сессии.
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "StartTrustedDeviceLogin",
|
||||
"requestId": "esp-start-001",
|
||||
"payload": {
|
||||
"login": "alice",
|
||||
"passwordHash": "sha256$0123abcd...",
|
||||
"requesterSessionKey": "ed25519/BASE64_PUBLIC_KEY",
|
||||
"requesterSessionType": 1,
|
||||
"requesterClientPlatform": "Android",
|
||||
"payloadType": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Если на доверённом устройстве вход включён **без доп. пароля**, новое устройство может отправить пустой `passwordHash`.
|
||||
|
||||
Поле `trustedSessionOnline` показывает, что у пользователя сейчас есть хотя бы одна онлайн доверенная сессия, способная принять pairing-заявку.
|
||||
Поле `shortCode` теперь содержит `10` цифр. В UI его рекомендуется показывать как `5` пар, например: `49 20 70 91 23`.
|
||||
|
||||
TTL заявки фиксирован на сервере и сейчас всегда равен `300` секундам.
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "StartTrustedDeviceLogin",
|
||||
"requestId": "esp-start-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"pairingId": "base64url",
|
||||
"state": "created",
|
||||
"shortCode": "4920709123",
|
||||
"fingerprintB58": "ASvYDPQidnAroKzQjtCjTuEQE8ckktV5nmmhYRhDzGaA",
|
||||
"expiresAtMs": 1781441990538,
|
||||
"trustedSessionOnline": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Ошибки
|
||||
|
||||
- `400 / EMPTY_LOGIN`
|
||||
- `400 / EMPTY_REQUESTER_SESSION_KEY`
|
||||
- `400 / BAD_REQUESTER_SESSION_KEY`
|
||||
- `400 / BAD_SESSION_TYPE`
|
||||
- `400 / BAD_PAYLOAD_TYPE`
|
||||
- `422 / PAIRING_NOT_AVAILABLE`
|
||||
- `422 / PAIRING_PASSWORD_INVALID` — pairing-пароль не подходит. Та же ошибка возвращается и если новое устройство ввело пароль, а у пользователя режим pairing включён без пароля.
|
||||
- `422 / PAIRING_NO_TRUSTED_SESSION_ONLINE` — сейчас нет ни одной онлайн доверённой сессии пользователя, поэтому код не создаётся.
|
||||
- `429 / PAIRING_RATE_LIMITED`
|
||||
|
||||
### 5.4. `ListTrustedDeviceLoginRequests`
|
||||
|
||||
Доступно для любой уже авторизованной доверенной сессии пользователя.
|
||||
Возвращает только реально активные pending-заявки со `state = created`. Уже `approved` и `rejected` заявки в этот список больше не попадают.
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "ListTrustedDeviceLoginRequests",
|
||||
"requestId": "esp-list-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"requests": [
|
||||
{
|
||||
"pairingId": "base64url",
|
||||
"state": "created",
|
||||
"requesterSessionKey": "ed25519/BASE64_PUBLIC_KEY",
|
||||
"requesterSessionType": 1,
|
||||
"requesterClientPlatform": "Android",
|
||||
"payloadType": 1,
|
||||
"shortCode": "4920709123",
|
||||
"fingerprintB58": "ASvYDPQidnAroKzQjtCjTuEQE8ckktV5nmmhYRhDzGaA",
|
||||
"createdAtMs": 1781441810538,
|
||||
"expiresAtMs": 1781441990538,
|
||||
"deliveredToHomeserver": true
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Ошибки
|
||||
|
||||
- `463 / PAIRING_REQUIRES_AUTH_SESSION`
|
||||
|
||||
### 5.5. `ApproveTrustedDeviceLogin`
|
||||
|
||||
Доступно для любой уже авторизованной доверенной сессии пользователя.
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "ApproveTrustedDeviceLogin",
|
||||
"requestId": "esp-approve-001",
|
||||
"payload": {
|
||||
"pairingId": "base64url",
|
||||
"encryptedPayload": "BASE64_OR_OTHER_OPAQUE_PAYLOAD"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "ApproveTrustedDeviceLogin",
|
||||
"requestId": "esp-approve-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"pairingId": "base64url",
|
||||
"state": "approved"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Ошибки
|
||||
|
||||
- `400 / EMPTY_PAIRING_ID`
|
||||
- `400 / EMPTY_ENCRYPTED_PAYLOAD`
|
||||
- `404 / PAIRING_NOT_FOUND`
|
||||
- `422 / PAIRING_OF_ANOTHER_USER`
|
||||
- `422 / PAIRING_NOT_PENDING`
|
||||
- `422 / PAIRING_EXPIRED`
|
||||
- `463 / PAIRING_REQUIRES_AUTH_SESSION`
|
||||
|
||||
### 5.6. `RejectTrustedDeviceLogin`
|
||||
|
||||
Доступно для любой уже авторизованной доверенной сессии пользователя. Похоже на approve, но переводит заявку в `state=rejected`.
|
||||
|
||||
### 5.7. `GetTrustedDeviceLoginStatus`
|
||||
|
||||
Операция для нового устройства.
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "GetTrustedDeviceLoginStatus",
|
||||
"requestId": "esp-status-001",
|
||||
"payload": {
|
||||
"pairingId": "base64url"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ после approve
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "GetTrustedDeviceLoginStatus",
|
||||
"requestId": "esp-status-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"pairingId": "base64url",
|
||||
"state": "approved",
|
||||
"shortCode": "4920709123",
|
||||
"fingerprintB58": "ASvYDPQidnAroKzQjtCjTuEQE8ckktV5nmmhYRhDzGaA",
|
||||
"payloadType": 1,
|
||||
"encryptedPayload": "AQIDBA==",
|
||||
"expiresAtMs": 1781441990538
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Возможные `state`
|
||||
|
||||
- `created`
|
||||
- `approved`
|
||||
- `rejected`
|
||||
- `canceled`
|
||||
- `expired`
|
||||
|
||||
### 5.8. `CancelTrustedDeviceLogin`
|
||||
|
||||
Операция для нового устройства, которое уже создало pairing-заявку и хочет принудительно снять ожидание до истечения TTL.
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "CancelTrustedDeviceLogin",
|
||||
"requestId": "esp-cancel-001",
|
||||
"payload": {
|
||||
"pairingId": "base64url",
|
||||
"requesterSessionKey": "ed25519/BASE64_PUBLIC_KEY"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "CancelTrustedDeviceLogin",
|
||||
"requestId": "esp-cancel-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"pairingId": "base64url",
|
||||
"state": "canceled"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Ошибки
|
||||
|
||||
- `400 / EMPTY_PAIRING_ID`
|
||||
- `400 / EMPTY_REQUESTER_SESSION_KEY`
|
||||
- `400 / BAD_REQUESTER_SESSION_KEY`
|
||||
- `404 / PAIRING_NOT_FOUND`
|
||||
- `422 / PAIRING_OF_ANOTHER_REQUESTER`
|
||||
- `422 / PAIRING_NOT_PENDING`
|
||||
@@ -0,0 +1,239 @@
|
||||
# API для разработчиков: 04 — Запись и чтение блока блокчейна
|
||||
|
||||
Документ описывает **текущий рабочий формат** сетевых вызовов:
|
||||
|
||||
- `AddBlock` — запись любого блока в блокчейн пользователя;
|
||||
- `GetBlockchainBlock` — публичное чтение одного конкретного блока по имени цепочки и номеру.
|
||||
|
||||
`GetBlockchainBlock` нужен в том числе для межсерверной синхронизации и для открытого чтения публичного блокчейна по одному блоку.
|
||||
|
||||
> Важный принцип: на уровне JSON API сейчас есть **один универсальный метод** записи — `AddBlock`.
|
||||
> Конкретный смысл записи задаётся типом самого бинарного блока (`type/subType/version` в заголовке блока).
|
||||
|
||||
## 1. Что делает `AddBlock`
|
||||
|
||||
`AddBlock`:
|
||||
- принимает имя блокчейна и base64 бинарного блока;
|
||||
- проверяет непрерывность цепочки (`blockNumber`, `prevHash`);
|
||||
- проверяет формат и подпись Ed25519;
|
||||
- валидирует `body` по правилам типа блока;
|
||||
- сохраняет блок и обновляет состояние цепочки.
|
||||
|
||||
## 2. JSON формат запроса
|
||||
|
||||
`op = "AddBlock"`.
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "AddBlock",
|
||||
"requestId": "req-1001",
|
||||
"payload": {
|
||||
"blockchainName": "alice-001",
|
||||
"blockNumber": 12,
|
||||
"prevBlockHash": "ab12...ff",
|
||||
"blockBytesB64": "AAAB..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Поля `payload`:
|
||||
- `blockchainName` — обязательно, формат `login-NNN`.
|
||||
- `blockNumber` — обязательно (временное legacy-поле для совместимости; должно совпасть с номером внутри бинарного блока).
|
||||
- `prevBlockHash` — legacy-поле, сейчас сервер использует `prevHash` из бинарного блока и состояние цепочки.
|
||||
- `blockBytesB64` — обязательно: **полный бинарный блок** (`preimage + sigMarker + signature`) в Base64.
|
||||
|
||||
## 3. Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "AddBlock",
|
||||
"requestId": "req-1001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"reasonCode": null,
|
||||
"serverLastGlobalNumber": 12,
|
||||
"serverLastGlobalHash": "9f0e...a1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 4. Ошибка (единый формат)
|
||||
|
||||
При ошибках сервер отдаёт `Net_Exception_Response` со стандартными полями и дополнительно с состоянием сервера для ресинка:
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "AddBlock",
|
||||
"requestId": "req-1001",
|
||||
"status": 400,
|
||||
"ok": false,
|
||||
"error": "bad_prev_hash",
|
||||
"message": "Некорректный prevHash (цепочка не совпадает)",
|
||||
"payload": {
|
||||
"serverLastGlobalNumber": 11,
|
||||
"serverLastGlobalHash": "c3d4...98"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Основные `reasonCode`
|
||||
|
||||
- `empty_blockchain_name`, `bad_blockchain_name`
|
||||
- `blockchain_state_not_found`
|
||||
- `bad_block_base64`, `bad_block_format`, `bad_block_body`
|
||||
- `bad_block_number`, `req_global_mismatch`, `bad_prev_hash`
|
||||
- `bad_signature`, `signature_verify_failed`
|
||||
- `prev_line_block_not_found`, `bad_prev_line_hash`
|
||||
- `limit_exceeded`
|
||||
- `chain_resync_in_progress` — цепочка временно заблокирована полным resync
|
||||
- `repost_disabled` — репосты временно отключены до будущей реализации
|
||||
- `internal_error`
|
||||
|
||||
## 5. Какие блоки реально можно добавлять через `AddBlock`
|
||||
|
||||
Через `AddBlock` можно писать поддержанные форматы, кроме явно отключённых временных фич:
|
||||
|
||||
1. **TECH (type=0)**
|
||||
- `HEADER_COMPAT (subType=0)`
|
||||
- `TECH_CREATE_CHANNEL (subType=1)`
|
||||
|
||||
2. **TEXT (type=1)**
|
||||
- `TEXT_POST (10)`
|
||||
- `TEXT_EDIT_POST (11)`
|
||||
- `TEXT_REPLY (20)`
|
||||
- `TEXT_EDIT_REPLY (21)`
|
||||
- `TEXT_REPOST (30)` — формат зарезервирован, но новые блоки временно отклоняются с `repost_disabled`
|
||||
|
||||
3. **REACTION (type=2)**
|
||||
- `REACTION_LIKE (1)`
|
||||
|
||||
4. **CONNECTION (type=3)**
|
||||
- `CONNECTION_FRIEND (10)`
|
||||
- `CONNECTION_UNFRIEND (11)`
|
||||
- `CONNECTION_CONTACT (20)`
|
||||
- `CONNECTION_UNCONTACT (21)`
|
||||
- `CONNECTION_FOLLOW (30)`
|
||||
- `CONNECTION_UNFOLLOW (31)`
|
||||
- `CONNECTION_SPOUSE (40)`
|
||||
- `CONNECTION_UNSPOUSE (41)`
|
||||
- `CONNECTION_PARENT (50)`
|
||||
- `CONNECTION_UNPARENT (51)`
|
||||
- `CONNECTION_CHILD (52)`
|
||||
- `CONNECTION_UNCHILD (53)`
|
||||
- `CONNECTION_SIBLING (54)`
|
||||
- `CONNECTION_UNSIBLING (55)`
|
||||
- `CONNECTION_KNOWN_PERSON (60)`
|
||||
- `CONNECTION_UNKNOWN_PERSON (61)`
|
||||
- `CONNECTION_SHINE_CONFIRMED (70)`
|
||||
- `CONNECTION_SHINE_UNCONFIRMED (71)`
|
||||
- `CONNECTION_SHINE_SEEN (74)`
|
||||
- `CONNECTION_SHINE_UNSEEN (75)`
|
||||
|
||||
5. **USER_PARAM (type=4)**
|
||||
- `USER_PARAM_TEXT_TEXT (1)`
|
||||
|
||||
## 6. Хватает ли функций сейчас
|
||||
|
||||
Коротко: **для записи событий в блокчейн — хватает**, для полноценного клиентского чтения — **пока не хватает**.
|
||||
|
||||
Что есть:
|
||||
- единый надёжный write-путь `AddBlock`;
|
||||
- есть `GetFriendsLists` и API по `UserParam`;
|
||||
- есть унифицированные коды ошибок и поля для ресинхронизации.
|
||||
|
||||
Что пока ограничивает продукт:
|
||||
- нет полноценного read API для каналов/постов/тредов;
|
||||
- нет API списка подписок с серверными счётчиками непрочитанного;
|
||||
- нет ленты событий (новые ответы/лайки/подписки) как отдельного RPC.
|
||||
|
||||
## 7. Рекомендации по клиенту при записи блоков
|
||||
|
||||
1. Перед отправкой держать локальный `lastNumber/lastHash`.
|
||||
2. При `bad_prev_hash` или `bad_block_number`:
|
||||
- взять `serverLastGlobalNumber/serverLastGlobalHash` из ошибки,
|
||||
- пересобрать следующий блок на актуальной вершине.
|
||||
3. Для edit-блоков всегда ссылаться на **оригинальный** блок, а не на предыдущий edit.
|
||||
4. Для связей/подписок использовать target на **root** (HEADER или CREATE_CHANNEL), а не на произвольный пост.
|
||||
|
||||
|
||||
## 8. USER_PARAM для «личных данных»
|
||||
|
||||
Да, на текущем API это можно добавить **без изменения серверного кода**:
|
||||
|
||||
- в `UserParam` поле `param` сейчас не ограничено фиксированным справочником;
|
||||
- сервер хранит пары `param -> value` как строки (при наличии корректной подписи и `time_ms`);
|
||||
- чтение уже есть через `GetUserParam` и `ListUserParams`.
|
||||
|
||||
Рекомендуемый стартовый набор ключей для профиля (MVP):
|
||||
|
||||
- `name`
|
||||
- `last_name`
|
||||
- `address_physical`
|
||||
- `address_web`
|
||||
- `phone`
|
||||
|
||||
Практическая рекомендация: заранее зафиксировать единый словарь ключей в клиенте/документации, чтобы избежать дублей вида `lastname` vs `last_name`, `site` vs `address_web` и т.д.
|
||||
|
||||
Ограничения, которые важно учесть:
|
||||
|
||||
- сейчас нет серверной ACL-политики чтения параметров (в MVP их может читать любой клиент, который знает `login`);
|
||||
- нет валидации формата значений для конкретных ключей (телефон, URL и т.д. проверяются только на стороне клиента);
|
||||
- нет отдельного индекса/поиска по этим полям — только точечное чтение и listing по `login`.
|
||||
|
||||
---
|
||||
|
||||
## 9. `GetBlockchainBlock`
|
||||
|
||||
### Назначение
|
||||
|
||||
Публичное чтение одного конкретного блока из цепочки.
|
||||
|
||||
Нужно для:
|
||||
|
||||
- открытого чтения блокчейна по одному блоку;
|
||||
- межсерверной синхронизации;
|
||||
- восстановления/докачки отсутствующего хвоста цепочки.
|
||||
|
||||
### JSON формат запроса
|
||||
|
||||
`op = "GetBlockchainBlock"`.
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "GetBlockchainBlock",
|
||||
"requestId": "req-2001",
|
||||
"payload": {
|
||||
"blockchainName": "alice-001",
|
||||
"blockNumber": 12
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Поля `payload`:
|
||||
|
||||
- `blockchainName` — обязательно, формат `login-NNN`.
|
||||
- `blockNumber` — обязательно, номер блока в цепочке, `>= 0`.
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "GetBlockchainBlock",
|
||||
"requestId": "req-2001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"blockchainName": "alice-001",
|
||||
"blockNumber": 12,
|
||||
"blockHash": "9f0eaabbccddeeff00112233445566778899aabbccddeeff0011223344556677",
|
||||
"blockBytesB64": "AAAB..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Ошибки
|
||||
|
||||
- `400 / BAD_FIELDS` — некорректные `blockchainName` или `blockNumber`.
|
||||
- `404 / BLOCK_NOT_FOUND` — такого блока нет.
|
||||
- `500 / INTERNAL_ERROR` — внутренняя ошибка сервера.
|
||||
@@ -0,0 +1,615 @@
|
||||
# API для разработчиков: Технические запросы
|
||||
|
||||
Этот файл описывает технические WebSocket-запросы, которые нужны для служебной работы клиента с сервером. Часть операций доступна без авторизации, часть требует успешной авторизованной сессии.
|
||||
|
||||
Сейчас здесь девять методов:
|
||||
|
||||
- `Ping` — keep-alive запрос для поддержания живого WebSocket-соединения;
|
||||
- `GetServerInfo` — запрос базовой публичной информации о сервере для выбора узла в децентрализованной сети;
|
||||
- `ListBlockchainHeads` — краткая сводка по всем локальным блокчейнам сервера для межсерверной синхронизации;
|
||||
- `GetSyncUserProfile` — межсерверный профиль пользователя для создания локальной цепочки без Solana RPC;
|
||||
- `SendSignal` — общий межсессионный технический сигнал в одну конкретную сессию или сразу во все активные сессии пользователя;
|
||||
- `GetCallIceConfig` — выдача STUN/TURN конфигурации для звонков;
|
||||
- `ClientErrorLog` — отправка клиентской ошибки в серверный лог;
|
||||
- `ClientDebugLog` — отправка клиентского debug-события в серверный буфер;
|
||||
- `CallDeliveryReport` — диагностический отчёт клиента о доставке/установке звонка.
|
||||
|
||||
Логика раздела такая:
|
||||
|
||||
- `Ping` нужен для регулярной проверки, что соединение всё ещё живо;
|
||||
- `GetServerInfo` нужен до авторизации и до работы с данными, чтобы клиент понял, что сервер доступен, и показал пользователю краткую карточку этого узла.
|
||||
- `ListBlockchainHeads` нужен для сервер-сервер сверки: партнёр получает список heads по всем цепочкам, сравнивает его со своим состоянием и затем добирает недостающие блоки по диапазону.
|
||||
- `GetSyncUserProfile` нужен для server-to-server режима, когда принимающий сервер хочет создать у себя локальные `solana_users + blockchain_state` без прямого обращения в Solana. Это используется как временный обход ограничений внешнего Solana RPC.
|
||||
- `SendSignal` нужен для доверенных межсессионных команд одного пользователя. Первое практическое применение — `remote AddBlock via homeserver session`, но формат задуман как общий transport на вырост.
|
||||
|
||||
Ниже сначала описаны назначение методов, затем точные форматы запросов и ответов.
|
||||
|
||||
## 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. `ListBlockchainHeads`
|
||||
|
||||
### Назначение
|
||||
|
||||
Запрос краткой сводки по всем локальным блокчейнам сервера.
|
||||
|
||||
Нужен для межсерверной синхронизации. Партнёр может:
|
||||
|
||||
- получить список всех блокчейнов;
|
||||
- сравнить `lastBlockNumber` и `lastBlockHash` со своими значениями;
|
||||
- понять, какие цепочки нужно догонять;
|
||||
- затем отдельно запросить недостающие блоки по диапазону.
|
||||
|
||||
Этот запрос доступен без авторизации.
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "ListBlockchainHeads",
|
||||
"requestId": "heads-001",
|
||||
"payload": {}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "ListBlockchainHeads",
|
||||
"requestId": "heads-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"blockchains": [
|
||||
{
|
||||
"blockchainName": "alice_main",
|
||||
"lastBlockNumber": 124,
|
||||
"lastBlockHash": "aabbccdd00112233445566778899aabbccddeeff00112233445566778899aabb",
|
||||
"fileSizeBytes": 58720
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Поля ответа
|
||||
|
||||
- `blockchains` — массив текущих heads всех цепочек сервера.
|
||||
- `blockchainName` — имя блокчейна.
|
||||
- `lastBlockNumber` — последний номер блока в этой цепочке.
|
||||
- `lastBlockHash` — последний хэш блока в HEX-формате `64` символа.
|
||||
- `fileSizeBytes` — текущий размер файла блокчейна в байтах.
|
||||
|
||||
### Специфические коды ошибок `ListBlockchainHeads`
|
||||
|
||||
- У `ListBlockchainHeads` нет специальных прикладных ошибок при штатной работе.
|
||||
- Если произойдёт непредвиденная проблема, сервер вернёт общую ошибку из раздела `00`, обычно `500 / INTERNAL_ERROR`.
|
||||
|
||||
---
|
||||
|
||||
## 4. `GetSyncUserProfile`
|
||||
|
||||
### Назначение
|
||||
|
||||
Запрос минимального профиля пользователя для межсерверной синхронизации.
|
||||
|
||||
Нужен в сценарии, когда сервер во время periodic sync увидел чужой блокчейн, которого у него локально ещё нет. Вместо обращения в Solana PDA он может запросить у партнёра:
|
||||
|
||||
- `login`
|
||||
- `blockchainName`
|
||||
- `solanaKey`
|
||||
- `blockchainKey`
|
||||
- `clientKey`
|
||||
- `blockchainSizeLimitBytes`
|
||||
|
||||
После этого принимающий сервер может локально создать записи в `solana_users` и `blockchain_state`, а затем уже докачивать блоки через `GetBlockchainBlock`.
|
||||
|
||||
Этот запрос доступен без авторизации и предназначен именно для server-to-server sync.
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "GetSyncUserProfile",
|
||||
"requestId": "sync-user-001",
|
||||
"payload": {
|
||||
"login": "alice"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ: пользователь не найден
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "GetSyncUserProfile",
|
||||
"requestId": "sync-user-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"exists": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ: пользователь найден
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "GetSyncUserProfile",
|
||||
"requestId": "sync-user-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"exists": true,
|
||||
"login": "alice",
|
||||
"blockchainName": "alice-001",
|
||||
"solanaKey": "BASE64_32",
|
||||
"blockchainKey": "BASE64_32",
|
||||
"clientKey": "BASE64_32",
|
||||
"blockchainSizeLimitBytes": 100000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Поля ответа
|
||||
|
||||
- `exists` — найден ли пользователь на сервере-партнёре.
|
||||
- `login` — канонический login из БД сервера-партнёра.
|
||||
- `blockchainName` — имя основной цепочки пользователя.
|
||||
- `solanaKey` — публичный ключ логина.
|
||||
- `blockchainKey` — публичный ключ блокчейна.
|
||||
- `clientKey` — публичный клиентский ключ, который в текущей модели используется при создании локальной записи.
|
||||
- `blockchainSizeLimitBytes` — лимит размера файла блокчейна, который будет записан в локальный `blockchain_state`.
|
||||
|
||||
### Специфические коды ошибок `GetSyncUserProfile`
|
||||
|
||||
- `400 / BAD_FIELDS` — пустой или некорректный `login`.
|
||||
- `404 / BLOCKCHAIN_STATE_NOT_FOUND` — пользователь найден, но на сервере-партнёре отсутствует `blockchain_state` для его цепочки.
|
||||
- При непредвиденной ошибке сервер вернёт общую ошибку из раздела `00`, обычно `500 / INTERNAL_ERROR`.
|
||||
|
||||
---
|
||||
|
||||
## 5. `SendSignal`
|
||||
|
||||
Доступно только после успешной авторизации.
|
||||
|
||||
### Назначение
|
||||
|
||||
Общий межсессионный технический сигнал.
|
||||
|
||||
Этот метод нужен для случаев, когда одна активная сессия пользователя должна быстро передать служебную команду другой сессии того же пользователя или сразу всем его активным сессиям.
|
||||
|
||||
Первый целевой сценарий:
|
||||
|
||||
- `remote AddBlock via homeserver session`
|
||||
|
||||
То есть телефон без локального `blockchain.key` может:
|
||||
|
||||
- подготовить только сырой payload операции без текущей вершины цепочки;
|
||||
- подписать сам `SendSignal` своим `session key`;
|
||||
- дополнительно подписать его `client key`, чтобы homeserver/ESP32 точно видел, что запрос пришёл от доверенного клиента этого же логина;
|
||||
- отправить запрос в выбранную `homeserver`-сессию;
|
||||
- получить от неё ответ после настоящего `AddBlock`, который homeserver соберёт и подпишет уже сама.
|
||||
|
||||
### Режимы доставки
|
||||
|
||||
- `targetMode = "single_session"` — доставка в одну конкретную `targetSessionId`.
|
||||
- `targetMode = "all_sessions"` — доставка во все активные сессии указанного логина.
|
||||
|
||||
### Важное правило подписи
|
||||
|
||||
Сам `SendSignal` не подписывает поле `data` отдельной вложенной подписью. Вместо этого сервер проверяет подписи по общему preimage сигнала, в который входит:
|
||||
|
||||
- `fromLogin`
|
||||
- `fromSessionId`
|
||||
- `toLogin`
|
||||
- `targetMode`
|
||||
- `targetSessionId`
|
||||
- `signalType`
|
||||
- `signalRequestId`
|
||||
- `timeMs`
|
||||
- `sha256(data)`
|
||||
|
||||
Поддерживаются две подписи:
|
||||
|
||||
- `sessionSignatureB64` — обязательная подпись текущей авторизованной `session key`;
|
||||
- `clientSignatureB64` — необязательная подпись `client key`.
|
||||
|
||||
Для сценария `remote AddBlock via homeserver` текущая договорённость такая:
|
||||
|
||||
- запрос должен идти только своему же логину;
|
||||
- запрос должен быть подписан и `session key`, и `client key`;
|
||||
- в будущем для отдельных wallet-сценариев `clientSignatureB64` может быть пустой.
|
||||
|
||||
### Запрос в одну сессию
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "SendSignal",
|
||||
"requestId": "ws-req-001",
|
||||
"payload": {
|
||||
"toLogin": "alice",
|
||||
"targetMode": "single_session",
|
||||
"targetSessionId": "sess-hs-001",
|
||||
"signalType": "remote_addblock_request",
|
||||
"signalRequestId": "remote-addblock-001",
|
||||
"data": "{\"operation\":\"remote_addblock_request\",\"signalRequestId\":\"remote-addblock-001\",\"blockchainName\":\"alice_main\",\"blockBodyB64\":\"...\"}",
|
||||
"timeMs": 1774700000123,
|
||||
"sessionSignatureB64": "BASE64_64",
|
||||
"clientSignatureB64": "BASE64_64"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "SendSignal",
|
||||
"requestId": "ws-req-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"deliveredCount": 1,
|
||||
"deliveredSessionIds": ["sess-hs-001"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Событие на принимающей стороне
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "IncomingSignal",
|
||||
"eventId": "evt-001",
|
||||
"payload": {
|
||||
"fromLogin": "alice",
|
||||
"fromSessionId": "sess-phone-001",
|
||||
"toLogin": "alice",
|
||||
"targetMode": "single_session",
|
||||
"targetSessionId": "sess-hs-001",
|
||||
"signalType": "remote_addblock_request",
|
||||
"signalRequestId": "remote-addblock-001",
|
||||
"data": "{\"operation\":\"remote_addblock_request\",\"signalRequestId\":\"remote-addblock-001\",\"blockchainName\":\"alice_main\",\"blockBodyB64\":\"...\"}",
|
||||
"timeMs": 1774700000123,
|
||||
"sessionSignatureB64": "BASE64_64",
|
||||
"clientSignatureB64": "BASE64_64",
|
||||
"dataSha256B64": "BASE64_32"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Специфика `remote AddBlock`
|
||||
|
||||
Для `remote_addblock_request` поле `data` теперь содержит:
|
||||
|
||||
- `blockchainName`
|
||||
- `blockBodyB64`
|
||||
|
||||
Где `blockBodyB64` — это не финальный блок и не почти готовый preimage, а компактный бинарный контейнер:
|
||||
|
||||
- `msgType` (`u16`)
|
||||
- `msgSubType` (`u16`)
|
||||
- `msgVersion` (`u16`)
|
||||
- `bodyBytes`
|
||||
|
||||
После этого homeserver сама:
|
||||
|
||||
- вызывает `GetUser(login)` и получает `serverLastGlobalNumber/serverLastGlobalHash`;
|
||||
- вычисляет новый `blockNumber = last + 1`;
|
||||
- подставляет актуальный `prevBlockHash`;
|
||||
- ставит текущее время;
|
||||
- досчитывает полный preimage;
|
||||
- подписывает его своим `blockchain key`;
|
||||
- и только потом делает настоящий `AddBlock`.
|
||||
|
||||
### Специфические коды ошибок `SendSignal`
|
||||
|
||||
- `422 / NOT_AUTHENTICATED` — требуется авторизация.
|
||||
- `400 / BAD_FIELDS` — не хватает обязательных полей или нарушено правило `single_session/all_sessions`.
|
||||
- `400 / BAD_TARGET_MODE` — передан неизвестный `targetMode`.
|
||||
- `400 / TIME_SKEW` — `timeMs` отличается от серверного более чем на 30 секунд.
|
||||
- `500 / NO_CLIENT_KEY` — для текущего пользователя не найден `client key`.
|
||||
- `404 / USER_NOT_FOUND` — логин адресата не найден.
|
||||
- `400 / BAD_DATA` — сервер не смог обработать `data`.
|
||||
- `400 / BAD_SESSION_SIGNATURE` — некорректная подпись `session key`.
|
||||
- `400 / BAD_CLIENT_SIGNATURE` — некорректная подпись `client key`.
|
||||
- `404 / SESSION_NOT_FOUND` — при `single_session` целевая сессия не найдена или не онлайн.
|
||||
- `404 / NO_TARGET_SESSIONS` — при `all_sessions` у пользователя сейчас нет активных онлайн-сессий.
|
||||
- `404 / DELIVERY_FAILED` — сервер не смог отправить событие ни в одну из целевых сессий.
|
||||
|
||||
---
|
||||
|
||||
## 6. `GetCallIceConfig`
|
||||
|
||||
Доступно только после успешной авторизации.
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "GetCallIceConfig",
|
||||
"requestId": "ice-001",
|
||||
"payload": {
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "GetCallIceConfig",
|
||||
"requestId": "ice-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"stunUrls": ["stun:stun.example.org:3478"],
|
||||
"turnUrls": ["turn:turn.example.org:3478?transport=udp"],
|
||||
"turnUsername": "user",
|
||||
"turnPassword": "password",
|
||||
"turnServers": [
|
||||
{
|
||||
"id": "primary",
|
||||
"urls": ["turn:turn.example.org:3478?transport=udp"],
|
||||
"username": "user",
|
||||
"password": "password"
|
||||
}
|
||||
],
|
||||
"turnEnabled": true,
|
||||
"generatedAtMs": 1774700000123,
|
||||
"expiresAtMs": 1774700300123,
|
||||
"ttlSec": 300
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Специфические коды ошибок `GetCallIceConfig`
|
||||
|
||||
- `422 / NOT_AUTHENTICATED` — требуется авторизация.
|
||||
|
||||
---
|
||||
|
||||
## 7. `ClientErrorLog`
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "ClientErrorLog",
|
||||
"requestId": "err-001",
|
||||
"payload": {
|
||||
"kind": "global_error",
|
||||
"message": "TypeError: failed",
|
||||
"stack": "...",
|
||||
"sourceUrl": "https://shineup.me/app.js",
|
||||
"lineNumber": 10,
|
||||
"columnNumber": 20,
|
||||
"route": "#/channel-view/own-0",
|
||||
"href": "https://shineup.me/#/channel-view/own-0",
|
||||
"userAgent": "...",
|
||||
"clientTs": 1774700000123,
|
||||
"requestOp": "GetChannelMessages",
|
||||
"requestIdRef": "GetChannelMessages-123",
|
||||
"contextJson": "{\"screen\":\"channels\"}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "ClientErrorLog",
|
||||
"requestId": "err-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"serverTs": 1774700000456,
|
||||
"accepted": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Специфические коды ошибок `ClientErrorLog`
|
||||
|
||||
- `400 / BAD_FIELDS` — обязательные поля ошибки не заполнены.
|
||||
|
||||
---
|
||||
|
||||
## 8. `ClientDebugLog`
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "ClientDebugLog",
|
||||
"requestId": "dbg-001",
|
||||
"payload": {
|
||||
"runId": "ui-run-1",
|
||||
"level": "info",
|
||||
"message": "opened channels tab",
|
||||
"details": "{\"route\":\"#/channels\"}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "ClientDebugLog",
|
||||
"requestId": "dbg-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"accepted": true,
|
||||
"serverTs": 1774700000456
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Специфические коды ошибок `ClientDebugLog`
|
||||
|
||||
- `400 / BAD_FIELDS` — поле `message` не заполнено.
|
||||
|
||||
---
|
||||
|
||||
## 9. `CallDeliveryReport`
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "CallDeliveryReport",
|
||||
"requestId": "call-report-001",
|
||||
"payload": {
|
||||
"type": "outgoing_failed",
|
||||
"value": "{\"reason\":\"ice_failed\",\"callId\":\"call-1\"}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "CallDeliveryReport",
|
||||
"requestId": "call-report-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"serverTs": 1774700000456,
|
||||
"accepted": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Специфические коды ошибок `CallDeliveryReport`
|
||||
|
||||
- `400 / BAD_FIELDS` — поле `type` не заполнено.
|
||||
|
||||
---
|
||||
|
||||
## 10. Короткое резюме
|
||||
|
||||
- `Ping` нужен для keep-alive и проверки, что WebSocket-соединение живо.
|
||||
- `GetServerInfo` нужен для выбора сервера в сети и показа публичной информации об узле.
|
||||
- `SendSignal` нужен для доверенных межсессионных сигналов одного пользователя, включая `remote AddBlock via homeserver session`.
|
||||
- `GetCallIceConfig` нужен для WebRTC-звонков и требует авторизации.
|
||||
- `ClientErrorLog`, `ClientDebugLog`, `CallDeliveryReport` используются для диагностики клиента и звонков.
|
||||
@@ -0,0 +1,341 @@
|
||||
# 06. Channels Read API
|
||||
|
||||
## Человеко-читаемое объяснение
|
||||
Эти функции — это **чтение данных каналов** для UI:
|
||||
|
||||
1. `ListSubscriptionsFeed` — отдает данные для экрана списка каналов:
|
||||
- ваши каналы (личный + созданные вами),
|
||||
- каналы пользователей, на кого вы подписаны,
|
||||
- отдельные каналы, на которые вы подписаны напрямую.
|
||||
|
||||
2. `GetChannelMessages` — отдает полную ленту одного канала (пока без курсоров, загружается сразу целиком),
|
||||
включая версии сообщений, лайки и ответы.
|
||||
|
||||
3. `GetMessageThread` — отдает дерево обсуждения вокруг конкретного сообщения:
|
||||
предки, фокус-сообщение, потомки.
|
||||
|
||||
4. `GetChannelsCounters` — отдает счетчики разделов каналов для пользователя.
|
||||
|
||||
5. `ListGroupChats200` — отдает список групповых чатов типа `200`.
|
||||
|
||||
6. `GetGroupDialog` — отдает сообщения конкретного группового чата типа `200`.
|
||||
|
||||
> На первом этапе мы **не используем курсоры** (`nextCursor`) и загружаем полные списки.
|
||||
|
||||
---
|
||||
|
||||
## 1) ListSubscriptionsFeed
|
||||
|
||||
### Request
|
||||
```json
|
||||
{
|
||||
"op": "ListSubscriptionsFeed",
|
||||
"requestId": "req-1",
|
||||
"payload": {
|
||||
"login": "Alice",
|
||||
"limit": 200
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response (success)
|
||||
```json
|
||||
{
|
||||
"op": "ListSubscriptionsFeed",
|
||||
"requestId": "req-1",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"login": "Alice",
|
||||
"ownedChannels": [
|
||||
{
|
||||
"channel": {
|
||||
"ownerLogin": "Alice",
|
||||
"ownerBlockchainName": "alice-001",
|
||||
"channelName": "0",
|
||||
"personal": true,
|
||||
"channelRoot": { "blockNumber": 0, "blockHash": "..." }
|
||||
},
|
||||
"messagesCount": 120,
|
||||
"lastMessage": {
|
||||
"messageRef": { "blockNumber": 921, "blockHash": "..." },
|
||||
"text": "последняя версия текста",
|
||||
"createdAtMs": 1760000000000,
|
||||
"authorLogin": "Alice",
|
||||
"authorBlockchainName": "alice-001"
|
||||
}
|
||||
}
|
||||
],
|
||||
"followedUsersChannels": [
|
||||
{
|
||||
"channel": {
|
||||
"ownerLogin": "Bob",
|
||||
"ownerBlockchainName": "bob-001",
|
||||
"channelName": "0",
|
||||
"personal": true,
|
||||
"channelRoot": { "blockNumber": 0, "blockHash": "..." }
|
||||
},
|
||||
"messagesCount": 540,
|
||||
"lastMessage": {
|
||||
"messageRef": { "blockNumber": 922, "blockHash": "..." },
|
||||
"text": "последняя версия текста",
|
||||
"createdAtMs": 1760000100000,
|
||||
"authorLogin": "Bob",
|
||||
"authorBlockchainName": "bob-001"
|
||||
}
|
||||
}
|
||||
],
|
||||
"followedChannels": [
|
||||
{
|
||||
"channel": {
|
||||
"ownerLogin": "Carl",
|
||||
"ownerBlockchainName": "carl-001",
|
||||
"channelName": "market",
|
||||
"personal": false,
|
||||
"channelRoot": { "blockNumber": 456, "blockHash": "..." }
|
||||
},
|
||||
"messagesCount": 90,
|
||||
"lastMessage": {
|
||||
"messageRef": { "blockNumber": 1002, "blockHash": "..." },
|
||||
"text": "актуальный текст",
|
||||
"createdAtMs": 1760001000000,
|
||||
"authorLogin": "Carl",
|
||||
"authorBlockchainName": "carl-001"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2) GetChannelMessages
|
||||
|
||||
### Request
|
||||
```json
|
||||
{
|
||||
"op": "GetChannelMessages",
|
||||
"requestId": "req-2",
|
||||
"payload": {
|
||||
"channel": {
|
||||
"ownerBlockchainName": "bob-001",
|
||||
"channelRootBlockNumber": 123,
|
||||
"channelRootBlockHash": "..."
|
||||
},
|
||||
"limit": 200,
|
||||
"sort": "asc"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response (success)
|
||||
```json
|
||||
{
|
||||
"op": "GetChannelMessages",
|
||||
"requestId": "req-2",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"channel": {
|
||||
"ownerLogin": "Bob",
|
||||
"ownerBlockchainName": "bob-001",
|
||||
"channelName": "news",
|
||||
"channelRoot": { "blockNumber": 123, "blockHash": "..." }
|
||||
},
|
||||
"messages": [
|
||||
{
|
||||
"messageRef": { "blockNumber": 140, "blockHash": "..." },
|
||||
"authorLogin": "Bob",
|
||||
"authorBlockchainName": "bob-001",
|
||||
"createdAtMs": 1760000000000,
|
||||
"text": "текущая версия",
|
||||
"likesCount": 12,
|
||||
"repliesCount": 3,
|
||||
"versionsTotal": 4,
|
||||
"versions": [
|
||||
{ "versionIndex": 1, "blockNumber": 140, "blockHash": "...", "text": "v1", "createdAtMs": 1760000000000 },
|
||||
{ "versionIndex": 2, "blockNumber": 155, "blockHash": "...", "text": "v2", "createdAtMs": 1760001000000 },
|
||||
{ "versionIndex": 3, "blockNumber": 170, "blockHash": "...", "text": "v3", "createdAtMs": 1760002000000 },
|
||||
{ "versionIndex": 4, "blockNumber": 199, "blockHash": "...", "text": "v4", "createdAtMs": 1760003000000 }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3) GetMessageThread
|
||||
|
||||
### Request
|
||||
```json
|
||||
{
|
||||
"op": "GetMessageThread",
|
||||
"requestId": "req-3",
|
||||
"payload": {
|
||||
"message": {
|
||||
"blockchainName": "bob-001",
|
||||
"blockNumber": 333,
|
||||
"blockHash": "..."
|
||||
},
|
||||
"depthUp": 20,
|
||||
"depthDown": 2,
|
||||
"limitChildrenPerNode": 50
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response (success)
|
||||
```json
|
||||
{
|
||||
"op": "GetMessageThread",
|
||||
"requestId": "req-3",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"ancestors": [MessageNode],
|
||||
"focus": MessageNode,
|
||||
"descendants": [MessageNodeTree]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### MessageNode (дополнение)
|
||||
- `MessageNode` расширяет формат сообщения из `GetChannelMessages` и дополнительно содержит:
|
||||
- `channelInfo` — мета-информация о канале (если применимо);
|
||||
- `rawBlockB64` — сырой `block_bytes` текущего блока в Base64.
|
||||
- Поле `rawBlockB64` присутствует у узлов во всех частях ответа `GetMessageThread`: `focus`, `ancestors[]`, `descendants[]`.
|
||||
- В `GetChannelMessages` поле `rawBlockB64` **не добавляется** (лента канала без сырого блока, чтобы не раздувать ответ).
|
||||
|
||||
---
|
||||
|
||||
## 4) GetChannelsCounters
|
||||
|
||||
### Request
|
||||
```json
|
||||
{
|
||||
"op": "GetChannelsCounters",
|
||||
"requestId": "req-4",
|
||||
"payload": {
|
||||
"login": "Alice"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response (success)
|
||||
```json
|
||||
{
|
||||
"op": "GetChannelsCounters",
|
||||
"requestId": "req-4",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"login": "Alice",
|
||||
"feedCount": 12,
|
||||
"dialogs100Count": 3,
|
||||
"groupChats200Count": 4,
|
||||
"myChannelsCount": 2
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5) ListGroupChats200
|
||||
|
||||
### Request
|
||||
```json
|
||||
{
|
||||
"op": "ListGroupChats200",
|
||||
"requestId": "req-5",
|
||||
"payload": {
|
||||
"login": "Alice"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response (success)
|
||||
```json
|
||||
{
|
||||
"op": "ListGroupChats200",
|
||||
"requestId": "req-5",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"login": "Alice",
|
||||
"chats": [
|
||||
{
|
||||
"ownerLogin": "Alice",
|
||||
"ownerBlockchainName": "alice-001",
|
||||
"channelRootBlockNumber": 123,
|
||||
"channelRootBlockHash": "...",
|
||||
"channelName": "team",
|
||||
"chatTitle": "Team chat",
|
||||
"membersCount": 3,
|
||||
"updatedAtMs": 1760000000000
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6) GetGroupDialog
|
||||
|
||||
### Request
|
||||
```json
|
||||
{
|
||||
"op": "GetGroupDialog",
|
||||
"requestId": "req-6",
|
||||
"payload": {
|
||||
"login": "Alice",
|
||||
"group": {
|
||||
"ownerBlockchainName": "alice-001",
|
||||
"channelRootBlockNumber": 123
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response (success)
|
||||
```json
|
||||
{
|
||||
"op": "GetGroupDialog",
|
||||
"requestId": "req-6",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"group": {
|
||||
"ownerLogin": "Alice",
|
||||
"ownerBlockchainName": "alice-001",
|
||||
"channelRootBlockNumber": 123,
|
||||
"channelName": "team",
|
||||
"chatTitle": "Team chat"
|
||||
},
|
||||
"messages": [
|
||||
{
|
||||
"authorLogin": "Bob",
|
||||
"authorBlockchainName": "bob-001",
|
||||
"blockNumber": 140,
|
||||
"blockHash": "...",
|
||||
"createdAtMs": 1760000000000,
|
||||
"text": "Привет"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Reason codes
|
||||
- `bad_fields`
|
||||
- `user_not_found`
|
||||
- `channel_not_found`
|
||||
- `message_not_found`
|
||||
- `limit_too_large`
|
||||
- `channel_name_already_exists`
|
||||
- `internal_error`
|
||||
@@ -0,0 +1,145 @@
|
||||
# 07. Channels Feature Runbook (человеческое описание + диагностика)
|
||||
|
||||
## 1) Что уже сделано простыми словами
|
||||
|
||||
Сейчас реализован полный минимальный контур для каналов:
|
||||
|
||||
1. **Серверные read API**:
|
||||
- `ListSubscriptionsFeed` — экран списка каналов.
|
||||
- `GetChannelMessages` — сообщения конкретного канала.
|
||||
- `GetMessageThread` — дерево обсуждения для сообщения.
|
||||
|
||||
2. **UI вкладки Каналы**:
|
||||
- при открытии пытается загрузить реальный feed с сервера;
|
||||
- если сервер недоступен — fallback на мок-данные;
|
||||
- группы каналов выводятся в нужном порядке;
|
||||
- есть кнопка «Добавить канал», модалки подписки, переход в канал.
|
||||
|
||||
3. **Проверка уникальности имени канала на сервере**
|
||||
- в `AddBlock` при `CreateChannelBody` добавлена проверка;
|
||||
- при дубле возвращается `409 channel_name_already_exists`.
|
||||
|
||||
---
|
||||
|
||||
## 2) Что тестировать в первую очередь (быстрый чеклист)
|
||||
|
||||
### Базовый smoke
|
||||
1. Авторизоваться в UI.
|
||||
2. Открыть вкладку «Каналы».
|
||||
3. Убедиться, что данные загрузились с сервера (или виден fallback-баннер).
|
||||
4. Нажать любой канал — должен открыться экран канала с сообщениями.
|
||||
|
||||
### API smoke
|
||||
1. Вызвать `ListSubscriptionsFeed`.
|
||||
2. Для канала `ownedChannels[0]` вызвать `GetChannelMessages`.
|
||||
3. Для первого `messages[0]` вызвать `GetMessageThread`.
|
||||
|
||||
### Ошибки
|
||||
1. `ListSubscriptionsFeed` с пустым login -> `bad_fields`.
|
||||
2. `GetChannelMessages` с битым channel payload -> `bad_fields`.
|
||||
3. `GetMessageThread` с несуществующим block -> `message_not_found`.
|
||||
4. `AddBlock(CreateChannel)` с уже существующим именем -> `channel_name_already_exists`.
|
||||
|
||||
---
|
||||
|
||||
## 3) Готовые JSON-запросы для ручной диагностики
|
||||
|
||||
## 3.1 ListSubscriptionsFeed
|
||||
```json
|
||||
{
|
||||
"op": "ListSubscriptionsFeed",
|
||||
"requestId": "debug-feed-1",
|
||||
"payload": {
|
||||
"login": "TestUser1",
|
||||
"limit": 200
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 3.2 GetChannelMessages
|
||||
```json
|
||||
{
|
||||
"op": "GetChannelMessages",
|
||||
"requestId": "debug-ch-1",
|
||||
"payload": {
|
||||
"channel": {
|
||||
"ownerBlockchainName": "TestUser1-001",
|
||||
"channelRootBlockNumber": 0,
|
||||
"channelRootBlockHash": ""
|
||||
},
|
||||
"limit": 200,
|
||||
"sort": "asc"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 3.3 GetMessageThread
|
||||
```json
|
||||
{
|
||||
"op": "GetMessageThread",
|
||||
"requestId": "debug-thread-1",
|
||||
"payload": {
|
||||
"message": {
|
||||
"blockchainName": "TestUser1-001",
|
||||
"blockNumber": 123,
|
||||
"blockHash": "<hash-from-GetChannelMessages>"
|
||||
},
|
||||
"depthUp": 20,
|
||||
"depthDown": 2,
|
||||
"limitChildrenPerNode": 50
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4) Что смотреть в ответах
|
||||
|
||||
### ListSubscriptionsFeed
|
||||
- `payload.login` — канонический login.
|
||||
- `ownedChannels / followedUsersChannels / followedChannels` — массивы.
|
||||
- у каждой записи есть:
|
||||
- `channel.channelRoot.blockNumber`,
|
||||
- `messagesCount`,
|
||||
- `lastMessage` (может быть null, если сообщений нет).
|
||||
|
||||
### GetChannelMessages
|
||||
- `payload.channel` заполнен;
|
||||
- `payload.messages[]` содержит:
|
||||
- `likesCount`, `repliesCount`,
|
||||
- `versionsTotal`, `versions[]`,
|
||||
- `text` должен быть текущей (последней) версией.
|
||||
|
||||
### GetMessageThread
|
||||
- `payload.ancestors[]`, `payload.focus`, `payload.descendants[]`.
|
||||
- у узлов должны быть версии и счетчики.
|
||||
- у каждого узла дополнительно может приходить `rawBlockB64` (Base64 сырого `block_bytes`).
|
||||
|
||||
### Важно по совместимости
|
||||
- `rawBlockB64` добавлен только в `GetMessageThread`.
|
||||
- `GetChannelMessages` не содержит `rawBlockB64` (без изменений формата ленты).
|
||||
|
||||
---
|
||||
|
||||
## 5) Частые проблемы и как быстро локализовать
|
||||
|
||||
1. **`status != 200`, code=bad_fields**
|
||||
- проверить вложенность payload и обязательные поля.
|
||||
|
||||
2. **`message_not_found` в GetMessageThread**
|
||||
- обычно передали blockNumber/hash не из `messageRef`.
|
||||
|
||||
3. **Пустой список сообщений в GetChannelMessages**
|
||||
- проверить `ownerBlockchainName` и `channelRootBlockNumber`.
|
||||
|
||||
4. **`channel_name_already_exists` при AddBlock**
|
||||
- это ожидаемо: в этой цепочке уже есть канал с таким именем.
|
||||
|
||||
---
|
||||
|
||||
## 6) Для будущей доработки
|
||||
|
||||
1. Добавить курсоры (пагинацию) для больших каналов.
|
||||
2. Перевести «Подписаться»/«Добавить канал» в UI с демо-заглушек на реальные write RPC.
|
||||
3. Добавить batch-агрегации для thread/versions (оптимизация).
|
||||
4. Добавить полноценные интеграционные тесты на негативные кейсы и нагрузку.
|
||||
@@ -0,0 +1,162 @@
|
||||
# MCP: чтение и дозапись персонального публичного чата (type=100)
|
||||
|
||||
Документ для реализации MCP-инструмента, который:
|
||||
- читает переписку между двумя логинами (`from`, `to`);
|
||||
- добавляет новое сообщение от отправителя через серверный `AddBlock`.
|
||||
|
||||
Важно: речь про **персональные публичные** каналы (`channelTypeCode=100`), а не приватные DM.
|
||||
|
||||
## 1. Базовые предпосылки
|
||||
|
||||
1. У каждого пользователя свой блокчейн (`<login>-001`).
|
||||
2. Персональный публичный чат хранится как канал типа `100`:
|
||||
- у `A` канал с `channelName = B`;
|
||||
- у `B` зеркальный канал с `channelName = A`.
|
||||
3. Сообщения канала — `TEXT_POST` и `TEXT_REPOST` в линии `line_code = rootBlockNumber` канала.
|
||||
4. Запись блока возможна только при валидной подписи blockchain-ключом владельца цепочки.
|
||||
|
||||
## 2. Что должен уметь MCP-инструмент
|
||||
|
||||
Минимальный набор операций:
|
||||
|
||||
1. `read_personal_public_dialog(fromLogin, toLogin, limitPerSide=200)`
|
||||
2. `append_personal_public_message(fromLogin, toLogin, text)`
|
||||
|
||||
## 3. Алгоритм чтения переписки
|
||||
|
||||
### 3.1 Найти оба канала (прямой и зеркальный)
|
||||
|
||||
Для `fromLogin = A`, `toLogin = B`:
|
||||
|
||||
1. Запросить `ListSubscriptionsFeed` для `A` и найти owned-канал:
|
||||
- `ownerLogin == A`
|
||||
- `channelName == B`
|
||||
- `channelTypeCode == 100`
|
||||
2. Запросить `ListSubscriptionsFeed` для `B` и найти owned-канал:
|
||||
- `ownerLogin == B`
|
||||
- `channelName == A`
|
||||
- `channelTypeCode == 100`
|
||||
|
||||
Если какой-то из каналов не найден — вернуть частичный результат + флаг отсутствия зеркала.
|
||||
|
||||
### 3.2 Вычитать сообщения из каналов
|
||||
|
||||
Для каждого найденного канала вызвать `GetChannelMessages`:
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "GetChannelMessages",
|
||||
"payload": {
|
||||
"login": "<текущий-login-сессии>",
|
||||
"channel": {
|
||||
"ownerBlockchainName": "...",
|
||||
"channelRootBlockNumber": 123,
|
||||
"channelRootBlockHash": "..."
|
||||
},
|
||||
"limit": 200,
|
||||
"sort": "asc"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 Склеить в единый диалог
|
||||
|
||||
1. Объединить массивы сообщений из `A->B` и `B->A`.
|
||||
2. Отсортировать по `createdAtMs`, при равенстве — по `messageRef.blockNumber`.
|
||||
3. Вернуть структуру:
|
||||
- `messages[]`
|
||||
- `directChannelFound` / `reverseChannelFound`
|
||||
- метаданные обоих каналов.
|
||||
|
||||
## 4. Алгоритм дозаписи сообщения
|
||||
|
||||
Цель: добавить сообщение **от имени `fromLogin`** в его канал `fromLogin -> toLogin`.
|
||||
|
||||
### 4.1 Найти канал отправителя
|
||||
|
||||
Через `ListSubscriptionsFeed(fromLogin)` найти owned-канал:
|
||||
- `channelName == toLogin`
|
||||
- `channelTypeCode == 100`
|
||||
|
||||
Если канал не найден — вернуть ошибку `channel_not_found`.
|
||||
|
||||
### 4.2 Отправить `AddBlock` с `TEXT_POST`
|
||||
|
||||
Использовать клиентский/серверный helper формирования `TEXT_POST` body:
|
||||
- `lineCode = channelRootBlockNumber`;
|
||||
- `prevLineNumber/prevLineHash` берутся из последнего сообщения линии;
|
||||
- подпись — blockchain private key пользователя `fromLogin`.
|
||||
|
||||
Если у вас в MCP нет приватного ключа пользователя, дозапись невозможна.
|
||||
|
||||
## 5. Контракт MCP (рекомендуемый)
|
||||
|
||||
## `read_personal_public_dialog`
|
||||
|
||||
Вход:
|
||||
```json
|
||||
{
|
||||
"fromLogin": "alice",
|
||||
"toLogin": "bob",
|
||||
"limitPerSide": 200
|
||||
}
|
||||
```
|
||||
|
||||
Выход:
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"directChannelFound": true,
|
||||
"reverseChannelFound": true,
|
||||
"messages": [
|
||||
{
|
||||
"authorLogin": "alice",
|
||||
"text": "Привет",
|
||||
"createdAtMs": 1760000000000,
|
||||
"channelSide": "alice->bob",
|
||||
"messageRef": { "blockNumber": 11, "blockHash": "..." }
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## `append_personal_public_message`
|
||||
|
||||
Вход:
|
||||
```json
|
||||
{
|
||||
"fromLogin": "alice",
|
||||
"toLogin": "bob",
|
||||
"text": "Тест"
|
||||
}
|
||||
```
|
||||
|
||||
Выход:
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"serverLastGlobalNumber": 321,
|
||||
"serverLastGlobalHash": "..."
|
||||
}
|
||||
```
|
||||
|
||||
## 6. Ограничения и безопасность
|
||||
|
||||
1. Персональный канал типа `100` сейчас публичный по модели чтения (не E2E DM).
|
||||
2. Нельзя дозаписать блок в чужой блокчейн без приватного ключа владельца (проверка подписи сервером).
|
||||
3. Для прод-инструмента нужно:
|
||||
- строгая авторизация MCP-вызовов;
|
||||
- аудит, кто и от чьего имени запрашивал чтение/запись;
|
||||
- лимиты/квоты на запись.
|
||||
|
||||
## 7. Мини-чеклист для реализации MCP
|
||||
|
||||
1. Реализовать helper поиска канала `findOwnedPersonalChannel(ownerLogin, peerLogin)`.
|
||||
2. Реализовать чтение двух сторон и merge/sort.
|
||||
3. Реализовать отправку `TEXT_POST` в найденный канал отправителя.
|
||||
4. Добавить понятные ошибки:
|
||||
- `user_not_found`
|
||||
- `channel_not_found`
|
||||
- `reverse_channel_not_found`
|
||||
- `signature_required`
|
||||
- `add_block_failed`
|
||||
@@ -0,0 +1,75 @@
|
||||
# API для разработчиков: индекс операций
|
||||
|
||||
Этот файл фиксирует полный список публичных JSON/WebSocket операций, зарегистрированных в коде сервера.
|
||||
|
||||
Источник истины на момент актуализации:
|
||||
|
||||
- `shine-server-net-protocol/src/main/java/server/logic/ws_protocol/JSON/JsonHandlerRegistry.java`.
|
||||
|
||||
Если операция есть в `HANDLERS` и `REQUEST_TYPES`, клиент может отправлять её как `op` в общем JSON-конверте из `00_Common_API_Format.md`.
|
||||
|
||||
## Актуальные операции
|
||||
|
||||
| Операция | Раздел документации | Кратко |
|
||||
| --- | --- | --- |
|
||||
| `AddUser` | `01_User_Registration_API.md` | отключено (`410 / ADD_USER_DISABLED`) |
|
||||
| `GetUser` | `01_User_Registration_API.md` | чтение/проверка пользователя + server-состояние его блокчейна |
|
||||
| `SearchUsers` | `01_User_Registration_API.md` | поиск логинов по префиксу |
|
||||
| `TestGetFreeAvatarQuota` | `14_Test_Free_Avatar_Upload_API.md` | временный тестовый просмотр остатка бесплатных загрузок аватара |
|
||||
| `TestUploadFreeAvatar` | `14_Test_Free_Avatar_Upload_API.md` | временная тестовая бесплатная загрузка маленького аватара в Arweave |
|
||||
| `AuthChallenge` | `02_Authentication_API.md` | challenge для создания новой сессии |
|
||||
| `CreateAuthSession` | `02_Authentication_API.md` | создание новой авторизованной сессии |
|
||||
| `SessionChallenge` | `02_Authentication_API.md` | challenge для входа в существующую сессию |
|
||||
| `SessionLogin` | `02_Authentication_API.md` | вход в существующую сессию |
|
||||
| `GetTrustedDeviceLoginSettings` | `03_Session_Management_API.md` | чтение текущего режима входа через доверенное устройство |
|
||||
| `UpsertTrustedDeviceLoginSettings` | `03_Session_Management_API.md` | включение/обновление pairing-настроек доверенной сессией |
|
||||
| `StartTrustedDeviceLogin` | `03_Session_Management_API.md` | создание pairing-заявки для нового устройства |
|
||||
| `ListTrustedDeviceLoginRequests` | `03_Session_Management_API.md` | список активных pairing-заявок для доверенной сессии |
|
||||
| `ApproveTrustedDeviceLogin` | `03_Session_Management_API.md` | подтверждение pairing-заявки доверенной сессией |
|
||||
| `RejectTrustedDeviceLogin` | `03_Session_Management_API.md` | отклонение pairing-заявки доверенной сессией |
|
||||
| `CancelTrustedDeviceLogin` | `03_Session_Management_API.md` | отмена pairing-заявки со стороны нового ожидающего устройства |
|
||||
| `GetTrustedDeviceLoginStatus` | `03_Session_Management_API.md` | чтение статуса и результата pairing-заявки |
|
||||
| `ListSessions` | `03_Session_Management_API.md` | список активных сессий |
|
||||
| `CloseActiveSession` | `03_Session_Management_API.md` | закрытие активной сессии |
|
||||
| `AddBlock` | `04_Add_Block_to_Blockchain_API.md` | добавление блока в блокчейн |
|
||||
| `GetBlockchainBlock` | `04_Add_Block_to_Blockchain_API.md` | чтение одного блока блокчейна |
|
||||
| `Ping` | `05_Technical_Requests_API.md` | keep-alive |
|
||||
| `GetServerInfo` | `05_Technical_Requests_API.md` | публичная информация о сервере |
|
||||
| `ListBlockchainHeads` | `05_Technical_Requests_API.md` | список heads всех локальных блокчейнов |
|
||||
| `GetSyncUserProfile` | `05_Technical_Requests_API.md` | межсерверный профиль пользователя для синхронизации |
|
||||
| `SendSignal` | `05_Technical_Requests_API.md` | общий межсессионный технический сигнал в одну или все сессии пользователя |
|
||||
| `GetCallIceConfig` | `05_Technical_Requests_API.md` | STUN/TURN конфигурация звонков |
|
||||
| `ClientErrorLog` | `05_Technical_Requests_API.md` | логирование клиентской ошибки |
|
||||
| `ClientDebugLog` | `05_Technical_Requests_API.md` | клиентский debug-лог |
|
||||
| `CallDeliveryReport` | `05_Technical_Requests_API.md` | диагностика доставки/установки звонков |
|
||||
| `ListSubscriptionsFeed` | `06_Channels_Read_API.md` | лента каналов/подписок |
|
||||
| `GetChannelMessages` | `06_Channels_Read_API.md` | сообщения канала |
|
||||
| `GetMessageThread` | `06_Channels_Read_API.md` | тред сообщения |
|
||||
| `GetChannelsCounters` | `06_Channels_Read_API.md` | счетчики разделов каналов |
|
||||
| `ListGroupChats200` | `06_Channels_Read_API.md` | список групповых чатов типа `200` |
|
||||
| `GetGroupDialog` | `06_Channels_Read_API.md` | сообщения группового чата типа `200` |
|
||||
| `UpsertUserParam` | `10_User_Params_API.md` | запись параметра пользователя |
|
||||
| `GetUserParam` | `10_User_Params_API.md` | чтение одного параметра пользователя |
|
||||
| `ListUserParams` | `10_User_Params_API.md` | список параметров пользователя |
|
||||
| `GetFriendsLists` | `11_Connections_API.md` | входящие/исходящие друзья |
|
||||
| `ListContacts` | `11_Connections_API.md` | контакты текущего пользователя |
|
||||
| `GetUserConnectionsGraph` | `11_Connections_API.md` | граф связей пользователя |
|
||||
| `AddCloseFriend` | `11_Connections_API.md` | добавить близкого друга |
|
||||
| `UpsertPushToken` | `12_Direct_Messages_Push_Calls_API.md` | регистрация WebPush-токена |
|
||||
| `SendTestWebPush` | `12_Direct_Messages_Push_Calls_API.md` | тестовая push-доставка |
|
||||
| `SendMessagePair` | `12_Direct_Messages_Push_Calls_API.md` | отправка пары входящий/исходящий DM |
|
||||
| `ReceiveOutcomingMessage` | `12_Direct_Messages_Push_Calls_API.md` | алиас `SendMessagePair` |
|
||||
| `ReceiveIncomingMessage` | `12_Direct_Messages_Push_Calls_API.md` | прием входящего DM-блока |
|
||||
| `DeleteMessage` | `12_Direct_Messages_Push_Calls_API.md` | tombstone одного личного сообщения у обеих сторон |
|
||||
| `DeleteConversation` | `12_Direct_Messages_Push_Calls_API.md` | tombstone удаления истории переписки |
|
||||
| `AckSessionDelivery` | `12_Direct_Messages_Push_Calls_API.md` | подтверждение доставки в сессию |
|
||||
| `CallInviteBroadcast` | `12_Direct_Messages_Push_Calls_API.md` | broadcast приглашения к звонку |
|
||||
| `CallSignalToSession` | `12_Direct_Messages_Push_Calls_API.md` | сигнал звонка в конкретную сессию |
|
||||
|
||||
## Важные замечания
|
||||
|
||||
- `ReceiveOutcomingMessage` сейчас зарегистрирован как алиас того же handler/request-класса, что и `SendMessagePair`.
|
||||
- Legacy-операция `SendDirectMessage` больше не зарегистрирована и не должна использоваться для DM v1.
|
||||
- Отдельных HTTP endpoints для DM-файлов сейчас нет.
|
||||
- Классы `Net_MarkChannelMessagesSeen_*` существуют в коде, но операция `MarkChannelMessagesSeen` не зарегистрирована в `JsonHandlerRegistry`, поэтому в публичный список API не входит.
|
||||
- HTTP debug endpoints из `src/main/java/server/debug/` не входят в этот индекс WebSocket `op`; они описаны отдельно в `13_HTTP_Debug_API.md`.
|
||||
@@ -0,0 +1,129 @@
|
||||
# API для разработчиков: параметры пользователя
|
||||
|
||||
Документ описывает операции для записи и чтения пользовательских параметров.
|
||||
|
||||
Текущие операции:
|
||||
|
||||
- `UpsertUserParam`
|
||||
- `GetUserParam`
|
||||
- `ListUserParams`
|
||||
|
||||
## 1. `UpsertUserParam`
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "UpsertUserParam",
|
||||
"requestId": "param-upsert-001",
|
||||
"payload": {
|
||||
"login": "alice",
|
||||
"param": "display_name",
|
||||
"time_ms": 1774700000123,
|
||||
"value": "Alice",
|
||||
"client_key": "BASE64_DEVICE_PUBLIC_KEY",
|
||||
"signature": "BASE64_SIGNATURE"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "UpsertUserParam",
|
||||
"requestId": "param-upsert-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Типовые ошибки
|
||||
|
||||
- `400 / BAD_FIELDS` — некорректные обязательные поля.
|
||||
- `422 / BAD_SIGNATURE` — подпись не прошла проверку.
|
||||
- `501 / DB_ERROR` — ошибка БД.
|
||||
|
||||
---
|
||||
|
||||
## 2. `GetUserParam`
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "GetUserParam",
|
||||
"requestId": "param-get-001",
|
||||
"payload": {
|
||||
"login": "alice",
|
||||
"param": "display_name"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "GetUserParam",
|
||||
"requestId": "param-get-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"login": "alice",
|
||||
"param": "display_name",
|
||||
"time_ms": 1774700000123,
|
||||
"value": "Alice",
|
||||
"client_key": "BASE64_DEVICE_PUBLIC_KEY",
|
||||
"signature": "BASE64_SIGNATURE"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Если параметр не найден, сервер возвращает `404` с пустым `payload`; отдельный прикладной код ошибки текущий handler не задаёт.
|
||||
|
||||
---
|
||||
|
||||
## 3. `ListUserParams`
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "ListUserParams",
|
||||
"requestId": "param-list-001",
|
||||
"payload": {
|
||||
"login": "alice"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "ListUserParams",
|
||||
"requestId": "param-list-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"login": "alice",
|
||||
"params": [
|
||||
{
|
||||
"login": "alice",
|
||||
"param": "display_name",
|
||||
"time_ms": 1774700000123,
|
||||
"value": "Alice",
|
||||
"client_key": "BASE64_DEVICE_PUBLIC_KEY",
|
||||
"signature": "BASE64_SIGNATURE"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Примечание
|
||||
|
||||
Имена JSON-полей `time_ms` и `client_key` сейчас соответствуют Java-модели ответа/запроса и должны передаваться именно в таком виде.
|
||||
@@ -0,0 +1,174 @@
|
||||
# API для разработчиков: связи пользователей
|
||||
|
||||
Документ описывает операции чтения и записи пользовательских связей.
|
||||
|
||||
Текущие операции:
|
||||
|
||||
- `GetFriendsLists`
|
||||
- `ListContacts`
|
||||
- `GetUserConnectionsGraph`
|
||||
- `AddCloseFriend`
|
||||
|
||||
## 1. `GetFriendsLists`
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "GetFriendsLists",
|
||||
"requestId": "friends-001",
|
||||
"payload": {
|
||||
"login": "alice"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "GetFriendsLists",
|
||||
"requestId": "friends-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"login": "Alice",
|
||||
"out_friends": ["Bob"],
|
||||
"in_friends": ["Kate"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. `ListContacts`
|
||||
|
||||
`ListContacts` использует текущую авторизованную сессию. В payload нет дополнительных полей.
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "ListContacts",
|
||||
"requestId": "contacts-001",
|
||||
"payload": {
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "ListContacts",
|
||||
"requestId": "contacts-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"login": "Alice",
|
||||
"contacts": ["Bob", "Kate"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. `GetUserConnectionsGraph`
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "GetUserConnectionsGraph",
|
||||
"requestId": "graph-001",
|
||||
"payload": {
|
||||
"login": "alice"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "GetUserConnectionsGraph",
|
||||
"requestId": "graph-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"login": "Alice",
|
||||
"outFriends": ["Bob"],
|
||||
"inFriends": ["Kate"],
|
||||
"outContacts": [],
|
||||
"inContacts": [],
|
||||
"outFollows": [],
|
||||
"inFollows": [],
|
||||
"outSpouses": [],
|
||||
"inSpouses": [],
|
||||
"outParents": [],
|
||||
"inParents": [],
|
||||
"outChildren": [],
|
||||
"inChildren": [],
|
||||
"outSiblings": [],
|
||||
"inSiblings": [],
|
||||
"outKnownPersons": [],
|
||||
"inKnownPersons": [],
|
||||
"outShineConfirmed": [],
|
||||
"inShineConfirmed": [],
|
||||
"outShineSeen": [],
|
||||
"inShineSeen": [],
|
||||
"parents": [],
|
||||
"children": [],
|
||||
"siblings": [],
|
||||
"spouses": [],
|
||||
"allUsers": [
|
||||
{
|
||||
"login": "Bob",
|
||||
"official": false,
|
||||
"shine": true,
|
||||
"officialLabel": "",
|
||||
"shineLabel": "shine",
|
||||
"avatar": { "ar": "..." }
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Примечание
|
||||
|
||||
Поля `known_person`, `shine_confirmed`, `shine_seen` в UI считаются недопроверенной зоной проекта; при изменениях этой логики нужна ручная end-to-end проверка.
|
||||
|
||||
---
|
||||
|
||||
## 4. `AddCloseFriend`
|
||||
|
||||
`AddCloseFriend` использует текущую авторизованную сессию как источник `login`.
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "AddCloseFriend",
|
||||
"requestId": "close-friend-001",
|
||||
"payload": {
|
||||
"toLogin": "bob"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "AddCloseFriend",
|
||||
"requestId": "close-friend-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"login": "Alice",
|
||||
"toLogin": "Bob",
|
||||
"relation": "close_friend"
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,235 @@
|
||||
# API для разработчиков: DM, push и сигналы звонков
|
||||
|
||||
Документ описывает публичные операции, связанные с личными сообщениями, WebPush и сигналами звонков.
|
||||
|
||||
Подробная логика DM и бинарного формата:
|
||||
|
||||
- `Dev_Docs/Personal_Messages/Протокол_DM_v1.md`
|
||||
- `Dev_Docs/Personal_Messages/Формат_DM_v1.md`
|
||||
|
||||
Важно:
|
||||
|
||||
- legacy-операция `SendDirectMessage` отключена и не зарегистрирована в публичном API;
|
||||
- для DM v1 нужно использовать только `SendMessagePair`, `ReceiveOutcomingMessage`, `ReceiveIncomingMessage`, `DeleteMessage`, `DeleteConversation`.
|
||||
|
||||
## 1. `UpsertPushToken`
|
||||
|
||||
Требует авторизации.
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "UpsertPushToken",
|
||||
"requestId": "push-upsert-001",
|
||||
"payload": {
|
||||
"sessionId": "SESSION_ID",
|
||||
"endpoint": "https://push.example/...",
|
||||
"p256dhKey": "BASE64",
|
||||
"authKey": "BASE64",
|
||||
"platform": "web",
|
||||
"userAgent": "Mozilla/5.0 ..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "UpsertPushToken",
|
||||
"requestId": "push-upsert-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"tokenId": "token-1",
|
||||
"updatedAtMs": 1774700000123
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 2. `SendTestWebPush`
|
||||
|
||||
Требует авторизации.
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "SendTestWebPush",
|
||||
"requestId": "push-test-001",
|
||||
"payload": {
|
||||
"login": "alice",
|
||||
"sessionId": "SESSION_ID",
|
||||
"title": "Test",
|
||||
"text": "Push body"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 3. `SendMessagePair` и `ReceiveOutcomingMessage`
|
||||
|
||||
`ReceiveOutcomingMessage` — алиас `SendMessagePair`.
|
||||
|
||||
### Назначение
|
||||
|
||||
Передаёт пару signed DM-блоков:
|
||||
|
||||
- `incomingBlobB64` — блок `type=1` или `type=3`
|
||||
- `outgoingBlobB64` — блок `type=2` или `type=4`
|
||||
|
||||
Все типы в этой паре используют бинарный формат `SHiNE_DM`.
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "SendMessagePair",
|
||||
"requestId": "dm-pair-001",
|
||||
"payload": {
|
||||
"incomingBlobB64": "BASE64_INCOMING_SIGNED_BLOCK",
|
||||
"outgoingBlobB64": "BASE64_OUTGOING_SIGNED_BLOCK"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "SendMessagePair",
|
||||
"requestId": "dm-pair-001",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"baseKey": "from|to|time|nonce",
|
||||
"incomingKey": "from|to|time|nonce|1",
|
||||
"outgoingKey": "from|to|time|nonce|2",
|
||||
"deliveredWsSessions": 1,
|
||||
"deliveredWebPushSessions": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Ошибки
|
||||
|
||||
- `400 / BAD_FIELDS` — пустой `incomingBlobB64` или `outgoingBlobB64`
|
||||
- `400 / BAD_BLOCK_FORMAT` — base64 или бинарный контейнер повреждён
|
||||
- `400 / BAD_CRYPTO_METHOD` — неподдерживаемый метод шифрования контейнера `EncryptedBody_v1_0`
|
||||
- `404 / USER_NOT_FOUND` — один из логинов не найден даже после попытки lazy-import из Solana PDA
|
||||
- `460 / BAD_SIGNATURE` — подпись блока не прошла проверку
|
||||
|
||||
## 4. `ReceiveIncomingMessage`
|
||||
|
||||
Принимает только один входящий signed DM-блок.
|
||||
|
||||
### Назначение
|
||||
|
||||
Используется там, где нужно принять только incoming-вариант сообщения.
|
||||
|
||||
Принимаемые типы:
|
||||
|
||||
- `type=1` — входящая копия сообщения
|
||||
- `type=3` — входящий read-receipt
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "ReceiveIncomingMessage",
|
||||
"requestId": "dm-in-001",
|
||||
"payload": {
|
||||
"incomingBlobB64": "BASE64_INCOMING_SIGNED_BLOCK"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 5. `DeleteMessage`
|
||||
|
||||
Принимает один signed DM-блок `type=5` или `type=6`.
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "DeleteMessage",
|
||||
"requestId": "dm-del-001",
|
||||
"payload": {
|
||||
"blobB64": "BASE64_DELETE_BLOCK"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 6. `DeleteConversation`
|
||||
|
||||
Принимает один signed DM-блок `type=7` или `type=8`.
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "DeleteConversation",
|
||||
"requestId": "dm-del-all-001",
|
||||
"payload": {
|
||||
"blobB64": "BASE64_DELETE_CONVERSATION_BLOCK"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 7. `AckSessionDelivery`
|
||||
|
||||
Требует авторизации. Подтверждает доставку в текущую сессию.
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "AckSessionDelivery",
|
||||
"requestId": "ack-001",
|
||||
"payload": {
|
||||
"messageKey": "from|to|time|nonce|1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 8. Событие `SignedMessageArrived`
|
||||
|
||||
Сервер присылает его по WebSocket в активные сессии адресата.
|
||||
|
||||
### Payload события
|
||||
|
||||
```json
|
||||
{
|
||||
"messageKey": "from|to|time|nonce|1",
|
||||
"baseKey": "from|to|time|nonce",
|
||||
"fromLogin": "alice",
|
||||
"toLogin": "bob",
|
||||
"targetLogin": "bob",
|
||||
"messageType": 1,
|
||||
"timeMs": 1774700000123,
|
||||
"nonce": 123456789,
|
||||
"blobB64": "BASE64_SIGNED_BLOCK",
|
||||
"backlog": false
|
||||
}
|
||||
```
|
||||
|
||||
Если это новая ревизия того же письма, `messageKey` остаётся тем же, а `revisionTimeMs` меняется внутри бинарного блока.
|
||||
|
||||
Для типов `5/6/7/8` событие тоже приходит в таком же конверте, но логика применения определяется `messageType` и бинарным `blobB64`.
|
||||
|
||||
## 9. `CallInviteBroadcast`
|
||||
|
||||
Требует авторизации. Шлёт приглашение к звонку в активные сессии `toLogin`.
|
||||
|
||||
## 10. `CallSignalToSession`
|
||||
|
||||
Требует авторизации. Шлёт сигнал звонка в конкретную сессию.
|
||||
|
||||
## 11. Замечания
|
||||
|
||||
- все DM-типы `1..8` используют `SHiNE_DM`
|
||||
- `GetUser` может lazy-import пользователя из Solana PDA, поэтому именно через него клиент обычно получает `clientKey` адресата для E2EE
|
||||
- сервер не расшифровывает DM и не использует ciphertext как preview текста
|
||||
- сервер хранит последнюю применённую версию контентного сообщения по правилу `revisionTimeMs`, а при равенстве — по `reencryptedAtMs`
|
||||
- если сервер уже знает tombstone удаления переписки и получает старое сообщение до этой границы, он перерассылает известный `DeleteConversation` на `access_servers` обеих сторон
|
||||
- HTTP endpoints для DM-файлов сейчас отсутствуют
|
||||
@@ -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.
|
||||
@@ -0,0 +1,176 @@
|
||||
# Временное Test API для бесплатной загрузки аватаров в Arweave
|
||||
|
||||
> Статус: **временное тестовое решение**.
|
||||
> Все операции из этого файла начинаются с `Test...`, чтобы это было видно сразу и в коде, и в UI.
|
||||
|
||||
## Назначение
|
||||
|
||||
Этот временный API даёт пользователю ограниченную бесплатную загрузку маленьких аватаров в Arweave:
|
||||
|
||||
- загрузка идёт через **серверный Arweave-кошелёк**;
|
||||
- лимит на пользователя: по умолчанию `3` загрузки за всё время;
|
||||
- лимит хранится в SQLite-таблице `test_free_avatar_uploads`;
|
||||
- если лимит исчерпан, сервер возвращает понятную ошибку;
|
||||
- загружать можно только маленький итоговый файл аватара, по умолчанию до `128 KB`.
|
||||
|
||||
## Настройки сервера
|
||||
|
||||
В `application.properties`:
|
||||
|
||||
```properties
|
||||
test.freeAvatar.enabled=true
|
||||
test.freeAvatar.gateway=https://arweave.net
|
||||
test.freeAvatar.limitPerUser=3
|
||||
test.freeAvatar.maxBytes=131072
|
||||
test.freeAvatar.walletAddress=
|
||||
test.freeAvatar.walletJwkPath=
|
||||
```
|
||||
|
||||
Пояснения:
|
||||
|
||||
- `test.freeAvatar.enabled` - включить или выключить временный API;
|
||||
- `test.freeAvatar.gateway` - Arweave gateway для `price/tx/wallet`;
|
||||
- `test.freeAvatar.limitPerUser` - пожизненный бесплатный лимит на пользователя;
|
||||
- `test.freeAvatar.maxBytes` - максимальный размер итогового файла;
|
||||
- `test.freeAvatar.walletAddress` - публичный адрес серверного Arweave-кошелька;
|
||||
- `test.freeAvatar.walletJwkPath` - путь к приватному JWK-файлу серверного кошелька.
|
||||
|
||||
Важно:
|
||||
|
||||
- приватный JWK хранится вне кода;
|
||||
- если `walletAddress` указан и не совпадает с адресом, вычисленным из JWK, сервер вернёт ошибку настройки.
|
||||
|
||||
## `TestGetFreeAvatarQuota`
|
||||
|
||||
Возвращает остаток бесплатных загрузок для текущего авторизованного пользователя.
|
||||
|
||||
### Запрос
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "TestGetFreeAvatarQuota",
|
||||
"requestId": "req-test-avatar-quota-1",
|
||||
"payload": {}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "TestGetFreeAvatarQuota",
|
||||
"requestId": "req-test-avatar-quota-1",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"enabled": true,
|
||||
"limit": 3,
|
||||
"usedCount": 1,
|
||||
"remainingCount": 2,
|
||||
"maxBytes": 131072
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Поля ответа
|
||||
|
||||
- `enabled` - временный API сейчас включён на сервере или нет;
|
||||
- `limit` - полный лимит бесплатных загрузок;
|
||||
- `usedCount` - сколько уже израсходовано;
|
||||
- `remainingCount` - сколько ещё осталось;
|
||||
- `maxBytes` - максимальный размер итогового файла.
|
||||
|
||||
### Ошибки
|
||||
|
||||
- `422 NOT_AUTHENTICATED` - требуется авторизация.
|
||||
|
||||
## `TestUploadFreeAvatar`
|
||||
|
||||
Временная бесплатная загрузка маленькой аватарки в Arweave через серверный кошелёк.
|
||||
|
||||
### Правила
|
||||
|
||||
- операция требует авторизованную сессию;
|
||||
- сервер использует текущий login из сессии;
|
||||
- сервер принимает только:
|
||||
- `image/jpeg`
|
||||
- `image/png`
|
||||
- `image/webp`
|
||||
- размер итогового файла должен быть не больше `maxBytes` из квоты;
|
||||
- если пользователь уже сделал `limit` бесплатных загрузок, операция запрещена.
|
||||
|
||||
### Запрос
|
||||
|
||||
`fileBytesBase64` - это обычный Base64 байт итогового подготовленного файла.
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "TestUploadFreeAvatar",
|
||||
"requestId": "req-test-avatar-upload-1",
|
||||
"payload": {
|
||||
"contentType": "image/webp",
|
||||
"fileBytesBase64": "UklGRiQAAABXRUJQVlA4WAoAAAAQAAAA...",
|
||||
"sha256Hex": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Успешный ответ
|
||||
|
||||
```json
|
||||
{
|
||||
"op": "TestUploadFreeAvatar",
|
||||
"requestId": "req-test-avatar-upload-1",
|
||||
"status": 200,
|
||||
"ok": true,
|
||||
"payload": {
|
||||
"txId": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
|
||||
"sha256Hex": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
|
||||
"usedCount": 2,
|
||||
"remainingCount": 1,
|
||||
"limit": 3,
|
||||
"gateway": "https://arweave.net"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Поля ответа
|
||||
|
||||
- `txId` - Arweave Transaction ID загруженного файла;
|
||||
- `sha256Hex` - SHA-256 загруженного файла;
|
||||
- `usedCount` - сколько бесплатных загрузок уже израсходовано после этой операции;
|
||||
- `remainingCount` - сколько бесплатных загрузок осталось;
|
||||
- `limit` - общий лимит;
|
||||
- `gateway` - gateway, через который сервер отправлял транзакцию.
|
||||
|
||||
### Ошибки
|
||||
|
||||
- `422 NOT_AUTHENTICATED` - требуется авторизация;
|
||||
- `400 BAD_FIELDS` - не переданы `contentType` или `fileBytesBase64`;
|
||||
- `400 BAD_BASE64` - `fileBytesBase64` не декодируется;
|
||||
- `400 BAD_AVATAR_FILE` - файл не проходит ограничения сервера;
|
||||
- `400 FREE_AVATAR_LIMIT_EXHAUSTED` - бесплатный лимит аватарок исчерпан;
|
||||
- `501 FREE_AVATAR_TEMP_DISABLED` - временная функция выключена или сервер не настроен;
|
||||
- `500 INTERNAL_ERROR` - внутренняя ошибка сервера.
|
||||
|
||||
## Как это используется в UI
|
||||
|
||||
На экране редактирования профиля в мастере смены аватара есть временный сценарий:
|
||||
|
||||
- `Залить аватар бесплатно`
|
||||
|
||||
UI:
|
||||
|
||||
1. вызывает `TestGetFreeAvatarQuota`;
|
||||
2. показывает остаток лимита;
|
||||
3. локально подготавливает уменьшенный файл аватара;
|
||||
4. проверяет, что итоговый файл не превышает `maxBytes`;
|
||||
5. вызывает `TestUploadFreeAvatar`;
|
||||
6. после получения `txId` обычным путём записывает `avatar.ar` в профиль через `AddBlock`.
|
||||
|
||||
## Почему решение временное
|
||||
|
||||
- используется общий серверный Arweave-кошелёк;
|
||||
- лимит хранится отдельной технической таблицей;
|
||||
- операции имеют префикс `Test...`;
|
||||
- сценарий нужен как переходный бесплатный путь для маленьких аватаров.
|
||||
Reference in New Issue
Block a user