Сохранить текущий снимок DM-синхронизации

2026-08-24 17:50:36 +04:00
parent 015fade4c0
commit d8e0c77951
48 changed files with 2498 additions and 383 deletions
@@ -62,11 +62,12 @@
 | `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` |
+| `ReceiveOutcomingMessage` | `12_Direct_Messages_Push_Calls_API.md` | старая полная DM-пара для второго access-сервера отправителя |
 | `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 удаления истории переписки |
-| `DmSyncBatch` | `12_Direct_Messages_Push_Calls_API.md` | межсерверная догоняющая синхронизация DM по курсору |
+| `DmSyncBatch` | `12_Direct_Messages_Push_Calls_API.md` | pull событий `synced=false` с ACK предыдущей страницы |
+| `GetDmDeliveryStatus` | `12_Direct_Messages_Push_Calls_API.md` | read-only статус доставки по существующему `messageKey` |
 | `UserSettingsSyncBatch` | `13_User_Settings_API.md` | межсерверная догоняющая синхронизация пользовательских настроек по курсору |
 | `MarkAllUserSettingsUnsynced` | `13_User_Settings_API.md` | служебная пометка всех настроек как несинхронизированных |
 | `GetDirectMessages` | `12_Direct_Messages_Push_Calls_API.md` | постраничная загрузка истории личного диалога |
@@ -76,7 +77,8 @@

 ## Важные замечания

- `ReceiveOutcomingMessage` сейчас зарегистрирован как алиас того же handler/request-класса, что и `SendMessagePair`.
+- `ReceiveOutcomingMessage` зарегистрирован как алиас того же handler/request-класса, что и `SendMessagePair`, и сохраняет прежний межсерверный payload.
+- Межсерверные DM-операции пока доверяют `sourceServerLogin`; отдельная межсерверная авторизация запланирована позднее.
 - Отдельных HTTP endpoints для DM-файлов сейчас нет.
 - Классы `Net_MarkChannelMessagesSeen_*` существуют в коде, но операция `MarkChannelMessagesSeen` не зарегистрирована в `JsonHandlerRegistry`, поэтому в публичный список API не входит.
 - HTTP debug endpoints из `src/main/java/server/debug/` не входят в этот индекс WebSocket `op`; они описаны отдельно в `13_HTTP_Debug_API.md`.
@@ -107,12 +107,17 @@
    "baseKey": "from|to|time|nonce",
    "incomingKey": "from|to|time|nonce|1",
    "outgoingKey": "from|to|time|nonce|2",
+    "deliveryState": "accepted",
    "deliveredWsSessions": 1,
    "deliveredWebPushSessions": 0
  }
 }
 ```

+Успешный `status=200` подтверждает локальное сохранение. До ответа клиенту сервер параллельно пробует оба актуальных сервера получателя. Поэтому `deliveryState` уже может быть `delivered`; если никто не ответил, возвращается `accepted`.
+
+Возможные `deliveryState`: `accepted`, `delivered`, `failed`.
+
 ### Ошибки

 - `400 / BAD_FIELDS` — пустой `incomingBlobB64` или `outgoingBlobB64`
@@ -147,7 +152,9 @@
 }
 ```

-`sourceServerLogin` необязателен. Если поле есть, сервер использует его как подсказку, чтобы не отправлять событие обратно серверу-источнику.
+`sourceServerLogin` необязателен для совместимости. Пока межсерверная авторизация отложена, это поле считается доверенным. Пользовательская подпись signed-блока проверяется всегда.
+
+Успешный ответ содержит существующие `messageKey`, `baseKey` и счётчики realtime-доставки. Повтор уже сохранённой той же ревизии обрабатывается идемпотентно.

 ### Примечание

@@ -243,6 +250,7 @@
        "reencryptedAtMs": 0,
        "createdAtMs": 1774700001123,
        "readAtMs": 1774700001456,
+        "deliveryState": "delivered",
        "blobB64": "BASE64_SIGNED_BLOCK"
      }
    ]
@@ -252,11 +260,50 @@

 Для следующей страницы клиент должен передать `nextBeforeTimeMs` и `nextBeforeMessageKey` из предыдущего ответа.

-## 8. `DmSyncBatch`
+Поле `deliveryState` заполняется для исходящих элементов `type=2`. У входящих `type=1` оно отсутствует/равно `null`.

-Межсерверная операция для догоняющей синхронизации истории одного пользователя. В текущей реализации не требует авторизации сервера-источника, но удалённый сервер отдаёт данные только если сам является access-сервером `ownerLogin` по `user_access_servers_current`.
+## 8. Межсерверные операции DM

-### Запрос
+До отдельного этапа server-auth поля `sourceServerLogin` доверяются. Каждый `SHiNE_DM` всё равно заново проходит проверку формата и пользовательской подписи.
+
+### 8.1. `ReceiveOutcomingMessage`
+
+Прежняя операция передачи полной пары второму access-серверу отправителя. Delivery-state в межсерверный запрос не входит.
+
+```json
+{
+  "op": "ReceiveOutcomingMessage",
+  "requestId": "dm-peer-001",
+  "payload": {
+    "incomingBlobB64": "BASE64_INCOMING",
+    "outgoingBlobB64": "BASE64_OUTGOING",
+    "sourceServerLogin": "server-a"
+  }
+}
+```
+
+Ответ имеет прежний формат `SendMessagePair`. Принимающий сервер сохраняет пару идемпотентно и самостоятельно ставит локальную задачу доставки.
+
+### 8.2. `ReceiveIncomingMessage`
+
+Прежняя операция передачи одной входящей копии серверу получателя или второму серверу самого получателя.
+
+```json
+{
+  "op": "ReceiveIncomingMessage",
+  "requestId": "dm-incoming-001",
+  "payload": {
+    "incomingBlobB64": "BASE64_INCOMING",
+    "sourceServerLogin": "server-a"
+  }
+}
+```
+
+Успешный 2xx-ответ означает, что signed-блок проверен и находится в БД (новая или идемпотентно повторённая запись).
+
+### 8.3. `DmSyncBatch`
+
+Pull-синхронизация событий владельца с `synced=false`. `ackSyncIds` подтверждает версии событий, успешно сохранённые из предыдущего ответа.

 ```json
 {
@@ -264,55 +311,58 @@
  "requestId": "dm-sync-001",
  "payload": {
    "ownerLogin": "alice",
-    "afterStoredAtMs": 1774700000000,
-    "afterMessageKey": "alice|bob|1774699999000|123456780|2",
+    "afterStoredAtMs": 0,
+    "afterMessageKey": "",
    "limit": 500,
-    "maxBytes": 3000000
+    "maxBytes": 3000000,
+    "ackSyncIds": []
  }
 }
 ```

-`afterStoredAtMs` и `afterMessageKey` образуют курсор. Если курсора нет, сервер передаёт `0` и пустую строку. `limit` ограничен максимумом `500`.
-
-### Успешный ответ
+Ответ возвращает страницу несинхронизированных событий и курсор внутри текущего цикла:

 ```json
 {
-  "op": "DmSyncBatch",
-  "requestId": "dm-sync-001",
-  "status": 200,
-  "ok": true,
+  "nextStoredAtMs": 1774700001123,
+  "nextMessageKey": "alice|bob|1774700000123|123456789|2",
+  "hasMore": false,
+  "items": [
+    {
+      "syncId": "alice|bob|1774700000123|123456789|2:0:0",
+      "primaryMessageKey": "alice|bob|1774700000123|123456789|2",
+      "storedAtMs": 1774700001123,
+      "blobsB64": ["BASE64_INCOMING", "BASE64_OUTGOING"]
+    }
+  ]
+}
+```
+
+Для пары порядок всегда incoming/outgoing; для входящей копии и tombstone массив содержит один blob. `syncId` — технический идентификатор конкретной ревизии только для ACK синхронизации, а не второй ID сообщения. После сохранения вызывающий сервер передаёт `syncId` в `ackSyncIds` следующего запроса. Только тогда источник ставит `synced=true`. Новый цикл начинается с `afterStoredAtMs=0`; полный сброс флагов поэтому повторно отдаёт всю историю.
+
+### 8.4. `GetDmDeliveryStatus`
+
+Единственная новая межсерверная операция доставки. Read-only проверка существующего `messageKey`; не изменяет состояние отвечающего сервера.
+
+```json
+{
+  "op": "GetDmDeliveryStatus",
+  "requestId": "dm-status-001",
  "payload": {
-    "ownerLogin": "alice",
-    "limit": 500,
-    "rawBytes": 84512,
-    "hasMore": true,
-    "nextStoredAtMs": 1774700100000,
-    "nextMessageKey": "alice|bob|1774700000123|123456789|1",
-    "items": [
-      {
-        "messageKey": "alice|bob|1774700000123|123456789|1",
-        "baseKey": "alice|bob|1774700000123|123456789",
-        "targetLogin": "alice",
-        "fromLogin": "bob",
-        "toLogin": "alice",
-        "messageType": 1,
-        "timeMs": 1774700000123,
-        "storedAtMs": 1774700100000,
-        "blobB64": "BASE64_SIGNED_BLOCK"
-      }
-    ]
+    "messageKey": "alice|bob|1774700000123|123456789|2"
  }
 }
 ```

-События в `items` идут по `storedAtMs ASC, messageKey ASC`. В пачке могут быть сообщения любых диалогов пользователя, read-receipt и delete/tombstone типов `5/6/7/8`.
+Ответ содержит `messageKey`, `known` и `delivered`. `delivered=true` означает доставку хотя бы одному серверу получателя.

-Ошибки:
+Периодический процесс использует одно WS-соединение с peer: сначала синхронизирует настройки, затем вызывает `DmSyncBatch` до завершения страниц и ACK. Существующий `MarkAllUserSettingsUnsynced` также сбрасывает DM-флаги и возвращает `dmUpdated`; отдельной операции `MarkAllDmUnsynced` нет.

- `400 / EMPTY_OWNER_LOGIN` — не передан `ownerLogin`
- `403 / LOCAL_SERVER_NOT_ACCESS_SERVER` — этот сервер не является access-сервером пользователя
- `500 / LOCAL_SERVER_NOT_CONFIGURED` — не настроен `server.SHiNE.login`
+Основные ошибки межсерверных операций:
+
+- `400 / EMPTY_OWNER_LOGIN`, `EMPTY_MESSAGE_KEY`;
+- `403 / LOCAL_SERVER_NOT_ACCESS_SERVER`;
+- `500 / LOCAL_SERVER_NOT_CONFIGURED`.

 ## 9. `AckSessionDelivery`

@@ -355,6 +405,25 @@

 Для типов `5/6/7/8` событие тоже приходит в таком же конверте, но логика применения определяется `messageType` и бинарным `blobB64`.

+## 10.1. Событие `DmDeliveryStateChanged`
+
+Сервер отправляет событие активным сессиям отправителя при изменении сетевого состояния исходящей пары.
+
+```json
+{
+  "op": "DmDeliveryStateChanged",
+  "event": true,
+  "status": 200,
+  "payload": {
+    "baseKey": "alice|bob|1774700000123|123456789",
+    "outgoingKey": "alice|bob|1774700000123|123456789|2",
+    "deliveryState": "delivered"
+  }
+}
+```
+
+`failed` приходит после последней неудачной попытки через час. Событие прочтения остаётся отдельным существующим read-receipt.
+
 ## 11. `CallInviteBroadcast`

 Требует авторизации. Шлёт приглашение к звонку в активные сессии `toLogin`.
@@ -77,15 +77,17 @@
 Внутренний служебный запрос.

 - помечает все настройки пользователя или все настройки сразу как `synced=false`;
+- одновременно сбрасывает DM-outbox того же пользователя (или всех пользователей), чтобы операция замены/добавления access-сервера не оставила историю DM несинхронизированной;
+- ответ дополнительно содержит `dmUpdated` — количество сброшенных DM-событий;
 - нужен после добавления нового sync-сервера или при потере локальной БД.

 ## 5. Синхронизация

-Синхронизация настроек работает отдельно от DM.
+Настройки и DM имеют раздельные таблицы и правила ACK, но периодический процесс открывает один последовательный WS-сеанс с peer: сначала синхронизирует настройки, затем забирает `DmSyncBatch`.

 - локальная запись создаётся с `synced=false`, если её ещё не подтвердил второй сервер;
 - если запись пришла с другого сервера, она сохраняется сразу как `synced=true`;
- периодический sync раз в 6 часов проверяет несинхронизированные записи и догружает новые записи по курсору;
+- периодический sync раз в 6 часов проверяет несинхронизированные настройки, догружает их по курсору и затем забирает несинхронизированные DM;
 - если появляется новый sync-сервер или локальная БД была потеряна, нужно пометить все настройки несинхронизированными и заново догрузить batch с нуля.

 ## 6. Текущий UI-кейс