Files
mtusi2026lab4/openspec/changes/upload-consistency/proposal.md
T
2026-10-21 05:17:35 +03:00

9.4 KiB
Raw Blame History

Proposal

Why

Рубрика «4» лабы 4 (README.md): прерывание загрузки и отказ между записью в S3 и в БД не должны оставлять вечных неучтённых объектов, нужен документированный механизм компенсации и очистки с безопасным grace period. Порядок записи с change attachments уже держит главный инвариант: строка pending с ключом объекта фиксируется до PUT. Но зависшие строки pending и их объекты сейчас никто не убирает, сбой фиксации ready после записи объекта не компенсируется, а ветка «строка pending пропала до ready» отвечает 500. Отсюда же ответ на вопрос защиты «Что произойдёт, если S3 PUT прошёл, а COMMIT в PostgreSQL — нет?».

What Changes

  • Компенсация в загрузке. PUT подтверждён, а перевод строки в ready не удался до отправки COMMIT — API сразу удаляет объект (без гарантии) и отвечает 503. Строка pending остаётся уборщику. Если исход COMMIT неизвестен, объект не трогается: решение принимает уборщик по строке. Строка pending, которую до ready убрал уборщик, — тоже компенсация и 503, а не 500. Порядок шагов загрузки не меняется.

  • Уборщик незавершённых загрузок — отдельный сервис compose cleaner на образе API, команда python -m src.cleaner:

    • раз в [cleaner] interval_seconds (60 с) находит строки pending старше [cleaner] pending_grace_seconds (900 с);
    • каждую строку берёт под блокировку (FOR UPDATE SKIP LOCKED), удаляет объект (отсутствие — не ошибка), затем строку, одним commit;
    • строки ready не трогает никогда;
    • при отказе S3 или БД строку оставляет и повторяет проход через интервал, без перезапуска;
    • --once — один проход для демонстрации и evidence.
  • Безопасный grace period. Уборщик не стартует, если grace не больше границы живой загрузки 2 × [database] request_timeout_seconds + [s3] timeout_seconds (17 с). Блокировка строки упорядочивает уборщика и ready загрузки, которая всё же пережила grace.

  • Свой пользователь S3 у уборщика: чтение и удаление объектов своего bucket, без записи, списка и прав на bucket. Его заводит и проверяет s3-bootstrap идемпотентно, как пользователя API. Ключи — новые секреты .env S3_CLEANER_ACCESS_KEY и S3_CLEANER_SECRET_KEY. make s3_check проверяет и их права.

  • Частичный индекс строк pending (created_at, id) — отдельной миграцией, без блокировки записи (CREATE INDEX CONCURRENTLY).

  • Тесты отказов (make failure_checks): уборщик на стенде отказов с grace 20 с и интервалом 1 с. Сценарии:

    • S3 остановлен и заморожен на время PUT;
    • сбой записи строки pending и сбой фиксации ready (триггер);
    • реплика убита между PUT и фиксацией;
    • обрыв клиента посреди тела;
    • невидимость pending через API (замечание verify attachments, S6);
    • свежая pending и готовые вложения уборщик не трогает;
    • уборщик переживает отказы S3 и БД.

    Итог каждого — нет 500, строка и объект убраны, объектов без строки нет. Hook получает новые действия, счётчики заменяются списками id: после DELETE SeaweedFS оставляет пустой каталог <id>/, и счёт по каталогам ошибается (проба).

  • Драйвер скилла: upload-consistency — тот же цикл на рабочем стенде через LB для evidence и защиты.

  • Evidence evidence/attachments/consistency.md, переснятый evidence/tests/failure-checks.md. В REPORT.md — согласованность БД и S3, grace и его обоснование, ответ на вопрос защиты.

Не входит:

  • лимит одновременных загрузок, сроки чтения тела, профиль uploads — upload-memory;
  • сверка списком bucket, объекты мимо API, строки ready без объекта, dry-run, стоимость обхода — трек 2 (track2-reconciler, track2-reconcile-cost);
  • запись KNOWN_ISSUES.md о bootstrap после удаления bucket — трек 2.

Шаг оператора: в существующий рабочий .env добавить две строки секретов уборщика. Без них compose не разбирает файл. Новый .env их получает от make env_setup.

Capabilities

New Capabilities

  • storage-consistency: согласованность метаданных вложений в PostgreSQL и объектов в S3. С лабы 4 — уборщик незавершённых загрузок: что и когда он убирает, безопасный grace period, поведение при отказах хранилищ. Сверку bucket и БД (трек 2) добавят следующие changes.

Modified Capabilities

  • attachments: «Порядок записи» — компенсация после подтверждённого PUT, 503 вместо 500 на сбоях после строки pending и при потере строки до ready, уборка — capability storage-consistency. Новые сценарии: невидимость pending, сбой записи строки, сбой фиксации ready, обрыв тела.
  • object-storage: bootstrap заводит пользователя уборщика; его ограниченные права; проверка прав в bootstrap и make s3_check; клиент работает с ключами своей роли.
  • container-run: уборщик в стенде compose, порядок старта, лимиты и секреты по сервисам.
  • service-configuration: секция [cleaner] и проверка grace при старте уборщика; секреты уборщика в новом .env.
  • service-logging: журнал уборщика.
  • graceful-shutdown: остановка уборщика по SIGTERM.
  • student-tests: сверка покрытия включает storage-consistency; новые проверки отказов, уборщик на стенде отказов, действия hook.

Impact

  • Код:
    • src/core/services/attachment.py — компенсация и ветки ошибок загрузки;
    • новый сервис уборки src/core/services/attachment_cleanup.py;
    • src/core/repos/attachment.py — кандидаты, блокировка, удаление; attachment_object.py — удаление объекта;
    • пакет src/cleaner/ — точка входа, цикл, сигналы;
    • src/infra/db/ — общий контекст короткой сессии, им пользуются API и уборщик;
    • src/infra/early_stop.py — имя процесса в записи;
    • src/config/settings.py — секция [cleaner]; модель Attachment — индекс; новая ревизия alembic.
  • Стенд:
    • docker-compose.yml (сервис cleaner, секреты), infra/s3/ bootstrap.sh, .env.example, config_example.toml, Makefile (env_setup);
    • bench/run.py (секреты), bench/bench.compose.yml (сервис описан, не запускается).
  • Тесты: student-tests/test_failures.py, fault_hook.py, run_failures.py, failures.compose.yml, spec_coverage.py.
  • Драйвер и документы: скилл run-mtusi-messenger (upload-consistency, строки s3-check); правила service-layer.md, repo-layer.md, infra.md, docker.md, settings.md, logging.md, run-modes.md, migrations.md, student-tests.md, balancer.md; AGENTS.md, REPORT.md, PLAN.md.
  • Регресс: make bench_quick и быстрые профили failover, rollout, restore; make failure_checks дольше примерно на 2 мин.