9.6 KiB
Proposal
Why
Уровень «5», трек 2 «Согласованность двух хранилищ» (README.md):
нужен повторяемый reconciler для объектов без метаданных и метаданных
без объектов. Ошибки вносятся с обеих сторон, reconciler их находит и
безопасно исправляет, с dry-run и повторным запуском. Свежие и
используемые вложения он не удаляет. Сейчас уборщик идёт только от строк
pending, и остаточные риски upload-consistency никто не находит
(REPORT.md, «Ограничения»):
- объект без строки — PUT-зомби после уборки, если компенсация не удалась;
- строка
readyбез объекта — откат шага 2 уборщика приmark_readyпрежней версии во время замены реплик.
Объект, удалённый мимо API, сейчас даёт 500 при каждом скачивании.
What Changes
-
Сверка bucket и БД — новый проход процесса уборщика. Он сравнивает объекты под
<база>/attachments/с метаданными той же базы. Классы расхождений:- объект без метаданных;
- метаданные
readyбез объекта; - другой размер;
- зависшая загрузка;
- вернувшийся оригинал;
- чужой объект (ключ, которого API не пишет).
-
Разовый проход —
python -m src.cleaner reconcile(make reconcile). По умолчанию это dry-run: отчёт по каждому расхождению (класс, ключ,id, возраст) и итог по классам. С--apply:- объект без метаданных удаляется;
- метаданные без объекта или с другим размером помечаются «оригинал потерян»;
- зависшая загрузка убирается порядком уборщика;
- с вернувшегося оригинала пометка снимается;
- чужой объект попадает только в отчёт.
Коды выхода: 0 — расхождений нет, 3 — остались, 1 — проход прерван, 2 — конфигурация. Повтор после исправления находит 0.
-
Плановая сверка в сервисе
cleaner: при старте и раз в[reconciler] interval_seconds(3600 с, 0 — выключена), с исправлением. Так объект без строки живёт не дольше grace + интервал, а не до ручного запуска. -
Безопасность:
- grace уборщика (900 с) по времени объекта в S3 и по времени метаданных;
- перепроверка в БД и в S3 непосредственно перед каждым действием;
- объект, на который ссылается строка, и строки
readyне удаляются никогда; - используемое вложение только помечается;
- отсутствие объекта не подтверждается без bucket;
- предел изменений за проход
[reconciler] max_changes(100): больше — ни одного изменения и код 3.
-
Потерянный оригинал. Колонка
attachments.lost_at, миграция только расширяет схему. Скачивание помеченного вложения — 404not_foundвместо 500. Метаданные — 200, как раньше, ссылка в сообщении — как раньше. Неоднозначность контракта — вопрос преподавателю (PLAN.md), это вариант по умолчанию. -
Права S3 пользователя
cleaner:s3:ListBucketтолько с префиксом<база>/attachments/(условиеs3:prefix, проверено на SeaweedFS 4.48). Список всего bucket, других префиксов и bucket-ов — 403. Bootstrap иmake s3_checkпроверяют это. -
Тесты отказов (
make failure_checks). Hook вносит расхождения:- объект мимо API;
- удалённый объект;
- удалённая или изменённая строка;
- обрыв загрузки между записью объекта и фиксацией.
Ещё hook запускает разовую сверку и уборщика с плановой сверкой. Проверки: dry-run, apply, повтор, свежие и используемые, чужой объект, предел, отказы S3 и БД, прерванный apply, сверка под нагрузкой.
-
Драйвер и evidence
evidence/reconcile/:reconcile-cycleна рабочем стенде — dry-run, apply, повтор = 0, возврат оригинала;reconcile-stress—--applyпод одновременными загрузками и отправками, затем каждое подтверждённое вложение скачивается с тем же SHA-256;- процесс сервиса, права S3, миграция.
Не входит — track2-reconcile-cost. Здесь одна стратегия: страницы
LIST по 1000 ключей и один запрос к БД на страницу, а точечные HEAD —
только для перепроверки найденного. Сверка поверхностная: наличие и
размер из LIST. Следующий change добавит:
- стратегию «HEAD на строку» (гипотеза 2);
- глубокую сверку SHA-256, выборочную или полную, и класс «другой SHA-256» (гипотеза 3);
- ограничение скорости обхода (гипотеза 4);
- профиль
reconcileстендаbench/, замеры, графики и выводы по гипотезам 1–4.
Гипотезу 5 («ничего подтверждённого не удалено») проверяет стресс этого change. Ещё не входят presigned upload, превью и 202 (лаба 5), отчёт и PR (этап 7).
Capabilities
New Capabilities
Нет.
Modified Capabilities
storage-consistency: новые требования — сверка bucket и БД, её безопасность, потерянный оригинал, отказы хранилищ во время сверки, плановая сверка; у уборщика объект без строки больше не остаётся навсегда.attachments: скачивание потерянного оригинала — 404, до пометки — 500.object-storage: список объектов у пользователя уборщика только по префиксу вложений своей базы, его проверка в bootstrap иmake s3_check, список объектов в клиенте.service-configuration: секция[reconciler].service-logging: журнал сверки и запись о потерянном оригинале.graceful-shutdown: остановка уборщика посреди сверки.student-tests: действия hook для расхождений и сверки, уборщик стенда отказов без плановой сверки.
Impact
- Код:
- новый
src/core/services/attachment_reconcile.py; src/core/repos/attachment.pyиattachment_object.py— выборки, пометка, список объектов;src/infra/s3/client.py— список страницами, время объекта;src/cleaner/— командаreconcile, плановая сверка, коды выхода;src/core/services/attachment.py— 404 потерянного оригинала;src/config/settings.py—[reconciler];- DTO и enum, модель
Attachmentи ревизия alembic.
- новый
- Стенд:
infra/s3/bootstrap.sh,docker-compose.yml(префикс списка уs3-bootstrap),config_example.toml,Makefile(reconcile),student-tests/failures.compose.yml. - Тесты:
student-tests/test_failures.py,fault_hook.py,run_failures.py. - Документы: скилл
run-mtusi-messenger(reconcile-cycle,reconcile-stress, строкиs3-check). Правилаservice-layer.md,repo-layer.md,dto.md,infra.md,migrations.md,docker.md,settings.md,logging.md,run-modes.md,api-contract.md,student-tests.md,balancer.md. Ещё AGENTS.md,REPORT.md,PLAN.mdиKNOWN_ISSUES.md— запись о bootstrap: причина найдена пробой, design, Context. - Регресс:
make failure_checksдольше ~3 мин,make s3_check(новые строки), быстрые профилиbench/(bench_rollout_quick— новая миграция),make test_isolated,make test-persistence.