Вернуть crash-safe запись AddBlock через tmp_bch

2026-06-26 17:05:37 +04:00
parent 1ced351ea2
commit 71fdee0cfd
10 changed files with 468 additions and 216 deletions
@@ -1,5 +1,13 @@
 # История изменений документации блокчейна

+## 2026-06-26 17:03:22 +0400
+- Базовый коммит-ориентир: `TBD`.
+- Обычный `AddBlock` переведён на crash-safe схему через временный кандидат `<blockchainName>.tmp_bch`, sidecar `<blockchainName>.write_check` и marker `<blockchainName>.write_pending`.
+- `BlockchainTmpRecoveryOnStartup` теперь разбирает marker-driven recovery для обычной записи блока:
+  - если marker есть, recovery либо завершает swap tmp -> main, либо удаляет мусор;
+  - если marker нет, временные артефакты считаются мусором и удаляются.
+- В `Dev_Docs/Blockchain/sync-between-servers.md` добавлено описание обычного `AddBlock` recovery и разделение между `write_pending` и `resync_pending`.
+
 ## 2026-05-24 11:40:00 +0300
 - Базовый коммит-ориентир: `abdce05`.
 - `TEXT_REPOST (subType=30)` оставлен как зарезервированный формат, но новые блоки репоста временно отключены на уровне `AddBlock`.
@@ -30,4 +30,5 @@

 ## Обязательное сопровождение
 - При любом изменении формата/правил блокчейна в коде документы этого каталога обновляются в том же наборе изменений.
+- Обычный `AddBlock` сейчас пишет через `<blockchainName>.tmp_bch`, `<blockchainName>.write_check` и `<blockchainName>.write_pending`; эта схема и `BlockchainTmpRecoveryOnStartup` должны быть описаны в актуальной документации по синхронизации и recovery.
 - Каждое обновление документов фиксируется в `CHANGELOG.md` с датой/временем и хэшем коммита-основания.
@@ -113,11 +113,28 @@ Full resync запускается только тогда, когда:
 - full resync не трогает DM-таблицы и `solana_users`;
 - висячие cross-chain ссылки считаются допустимым поведением системы.

-### 4.5 Startup recovery по marker-file
+### 4.5 Как работает обычный `AddBlock` и его recovery
+
+Обычная запись блока теперь тоже идёт через временные артефакты:
+
+1. собирается `<blockchainName>.tmp_bch` как полный кандидат на замену основного файла;
+2. пишется маленький sidecar `<blockchainName>.write_check` с `blockNumber` и `blockHash`;
+3. только после этого создаётся пустой marker `<blockchainName>.write_pending`;
+4. выполняется SQL-транзакция;
+5. после `commit` tmp атомарно ставится на место основного `.bch`;
+6. marker и sidecar удаляются.
+
+На старте `BlockchainTmpRecoveryOnStartup` смотрит именно на эту пару:
+
+- если `write_pending` есть, recovery проверяет sidecar и БД, а затем либо завершает swap, либо чистит временные файлы;
+- если `write_pending` нет, а `tmp_bch` или `write_check` остались, это мусор и он удаляется;
+- `resync_pending` сюда не относится, это отдельный recovery-поток.
+
+### 4.6 Startup recovery по marker-file

 При старте сервер идёт в таком порядке:

-1. `BlockchainTmpRecoveryOnStartup` для `*.tmp_bch`;
+1. `BlockchainTmpRecoveryOnStartup` для `*.write_pending` и orphan `*.tmp_bch` / `*.write_check`;
 2. `BlockchainResyncRecoveryOnStartup` для `*.resync_pending`;
 3. только потом поднимается обычный сервер и запускается `PeriodicBlockchainSyncService`.

@@ -127,7 +144,7 @@ Full resync запускается только тогда, когда:
 - recovery снова выполняет cleanup и replay с нуля;
 - если recovery не завершился, marker остаётся, и сервер не переходит к обычному режиму для этой chain.

-### 4.6 Зачем понадобился `GetSyncUserProfile`
+### 4.7 Зачем понадобился `GetSyncUserProfile`

 Изначально подготовка локальной цепочки делалась через Solana:

@@ -145,7 +162,7 @@ Full resync запускается только тогда, когда:

 Это временная практическая заплатка, чтобы clean-start sync не зависел от rate limit внешнего Solana endpoint.

-### 4.7 Что делает настройка `sync.importUserProfileFromPartner.enabled`
+### 4.8 Что делает настройка `sync.importUserProfileFromPartner.enabled`

 - `false` — стандартный режим, подготовка локального пользователя идёт через Solana PDA;
 - `true` — sync-режим обхода Solana, локальный пользователь создаётся по server-to-server `GetSyncUserProfile`.
@@ -209,6 +226,7 @@ Full resync запускается только тогда, когда:
 | Публичный `GetSyncUserProfile` | ✅ Реализовано |
 | Плановый blockchain sync при старте + каждые 12 часов | ✅ Реализовано |
 | Обход Solana RPC через `sync.importUserProfileFromPartner.enabled` | ✅ Реализовано |
+| Обычный `AddBlock` через `tmp_bch`/`write_check`/`write_pending` | ✅ Реализовано |
 | Межсерверный постоянный WebSocket-канал | Нужна реализация |
 | Push новых DM партнёрам | Нужна реализация |
 | Push блоков блокчейна партнёрам | ✅ Реализована базовая one-shot версия |
@@ -221,5 +239,4 @@ Full resync запускается только тогда, когда:
 Не реализованы ещё DM-sync и постоянные server-to-server соединения.

 Следующие отдельные шаги после текущего этапа:
- вернуть обычному `AddBlock` настоящую `tmp_bch`-схему записи и recovery при резком рестарте.
 - отдельно проверить full-resync и startup-recovery на реальном тестовом прогоне после ручного удаления БД/файлов.