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

9.6 KiB
Raw Blame History

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.