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

134 lines
9.4 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
Рубрика «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 мин.