147 lines
9.6 KiB
Markdown
147 lines
9.6 KiB
Markdown
# 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`, миграция
|
||
только расширяет схему. Скачивание помеченного вложения — 404
|
||
`not_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`.
|