НЕ ПРОВЕРЕНО: откат DM-вложений, оставлены ревизии и удаление

2026-06-18 12:24:14 +04:00
parent 92fd315505
commit a95bd245cf
23 changed files with 309 additions and 1267 deletions
@@ -1,8 +1,10 @@
-# API для разработчиков: DM, файлы, push и сигналы звонков
+# API для разработчиков: DM, push и сигналы звонков

-Документ описывает публичные операции и endpoints, связанные с личными сообщениями, файлами для DM, WebPush и сигналами звонков.
+Документ описывает публичные операции, связанные с личными сообщениями, WebPush и сигналами звонков.

-Подробная логика DM и бинарного формата: `Dev_Docs/Personal_Messages/README.md`.
+Подробная логика DM и бинарного формата:
+
+- `Dev_Docs/Personal_Messages/README.md`

 ## 1. `UpsertPushToken`

@@ -70,7 +72,7 @@
 - `incomingBlobB64` — блок `type=1` или `type=3`
 - `outgoingBlobB64` — блок `type=2` или `type=4`

-Для контентных сообщений `type=1/2` внутри base64 лежит новый бинарный формат `SHiNE_DM`.
+Для контентных сообщений `type=1/2` внутри base64 лежит бинарный формат `SHiNE_DM`.

 ### Запрос

@@ -108,12 +110,31 @@
 - `400 / BAD_FIELDS` — пустой `incomingBlobB64` или `outgoingBlobB64`
 - `400 / BAD_BLOCK_FORMAT` — base64 или бинарный контейнер повреждён
 - `400 / BAD_CONTENT_FORMAT` — для контентного сообщения пришёл не `SHiNE_DM`
- `400 / TOO_MANY_ATTACHMENTS` — больше 12 вложений
- `400 / ATTACHMENT_NOT_FOUND` — сообщение ссылается на blob, которого нет на сервере
+- `400 / ATTACHMENTS_DISABLED` — в `SHiNE_DM` пришёл `attachmentsCount != 0`
 - `404 / USER_NOT_FOUND` — один из логинов не найден
 - `460 / BAD_SIGNATURE` — подпись блока не прошла проверку

-## 4. `AckSessionDelivery`
+## 4. `ReceiveIncomingMessage`
+
+Принимает только один входящий signed DM-блок.
+
+### Назначение
+
+Используется там, где нужно принять только incoming-вариант сообщения.
+
+### Запрос
+
+```json
+{
+  "op": "ReceiveIncomingMessage",
+  "requestId": "dm-in-001",
+  "payload": {
+    "incomingBlobB64": "BASE64_INCOMING_SIGNED_BLOCK"
+  }
+}
+```
+
+## 5. `AckSessionDelivery`

 Требует авторизации. Подтверждает доставку в текущую сессию.

@@ -129,7 +150,7 @@
 }
 ```

-## 5. Событие `SignedMessageArrived`
+## 6. Событие `SignedMessageArrived`

 Сервер присылает его по WebSocket в активные сессии адресата.

@@ -152,71 +173,18 @@

 Если это новая ревизия того же письма, `messageKey` остаётся тем же, а `revisionTimeMs` меняется внутри бинарного блока.

-## 6. HTTP `HEAD /f/<hashB64url>`
-
-Проверка, есть ли ciphertext-файл на сервере.
-
-### Ответы
-
- `200` — файл существует
- `404` — файла нет
-
-## 7. HTTP `GET /f/<hashB64url>`
-
-Отдаёт ciphertext-файл.
-
-### Особенности
-
- `Content-Type: application/octet-stream`
- файл сейчас доступен публично
- имя файла на диске и в URL — `base64url(SHA-256(ciphertext))`
-
-## 8. HTTP `POST /upload?hash=<hashB64url>&size=<bytes>`
-
-Загружает ciphertext-файл для будущего DM.
-
-### Тело запроса
-
-Raw bytes ciphertext-файла.
-
-### Поведение сервера
-
- пересчитывает `SHA-256`
- сверяет размер
- сохраняет blob в папку `f/`, если его ещё не было
- если blob уже есть, не перезаписывает его
- создаёт или обновляет запись в `dm_files`
-
-### Успешный ответ
-
-```json
-{
-  "ok": true,
-  "hash": "base64url_sha256",
-  "size": 245120,
-  "alreadyExists": false
-}
-```
-
-### Ошибки
-
- `400 / bad hash`
- `400 / bad size`
- `400 / SIZE_MISMATCH`
- `400 / HASH_MISMATCH`
- `400 / UPLOAD_TOO_LARGE`
- `500 / upload_failed`
-
-## 9. `CallInviteBroadcast`
+## 7. `CallInviteBroadcast`

 Требует авторизации. Шлёт приглашение к звонку в активные сессии `toLogin`.

-## 10. `CallSignalToSession`
+## 8. `CallSignalToSession`

 Требует авторизации. Шлёт сигнал звонка в конкретную сессию.

-## 11. Замечания
+## 9. Замечания

- Для нового DM-файла сценарий такой: `HEAD /f/<hash>` → при `404` `POST /upload` → затем `SendMessagePair`.
- Сервер хранит только последнюю версию контентного сообщения по `messageKey`.
- Удаление сообщения реализуется новой ревизией с пустым телом и нулём вложений.
+- read-receipt `type=3/4` пока остаются в legacy-формате `SHiNE_dm2`
+- контентные DM `type=1/2` используют `SHiNE_DM`
+- сервер хранит только последнюю версию контентного сообщения по `messageKey`
+- удаление сообщения реализуется новой ревизией с пустым телом и `attachmentsCount = 0`
+- HTTP endpoints для DM-файлов сейчас отсутствуют