134 lines
9.4 KiB
Markdown
134 lines
9.4 KiB
Markdown
# 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 мин.
|