9.4 KiB
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. Ключи — новые секреты.envS3_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 (замечание verifyattachments, 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, уборка — capabilitystorage-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 мин.