# 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 оставляет пустой каталог `/`, и счёт по каталогам ошибается (проба). - Драйвер скилла: `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 мин.