Files
mtusi2026lab4/openspec/changes/track2-reconciler/proposal.md
T
2026-10-22 17:06:14 +03:00

147 lines
9.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`.