diff --git a/.claude/rules/balancer.md b/.claude/rules/balancer.md index daf6cfc0..4d61da10 100644 --- a/.claude/rules/balancer.md +++ b/.claude/rules/balancer.md @@ -312,14 +312,24 @@ rolling_update` уборщик работает на прежнем образе только расширяется (индекс). Новый код уборщика — `docker compose up -d --no-deps cleaner` или `make run_docker`; его SIGTERM доводит текущий шаг строки и выходит за ≤ 6 с. Пометка строки к уборке (verify W1, -design `upload-consistency`, «Уточнения apply», п. 16) защищает от -`ready` без объекта, только когда новые и реплики, и уборщик: прежний -уборщик строку не помечает, а реплики прежней версии пометку не -проверяют. До конца замены и `up -d --no-deps cleaner` действует -прежний остаточный риск (загрузка, пережившая grace, при откате -транзакции уборщика), это ограничение в `REPORT.md`. Обратная -совместимость есть: новый `mark_ready` на строках, вставленных прежним -кодом, работает (вставка всегда писала `created_at` = `updated_at`). +design `upload-consistency`, «Уточнения apply», п. 16 и 21) полностью +защищает от `ready` без объекта, только когда новые и реплики, и +уборщик. Смеси версий не хуже, чем до правки: +- новый уборщик + реплики до `87c48b9` (пометку не проверяют): объект и + строка удаляются одной транзакцией под блокировкой, поэтому прежний + `mark_ready` либо делает строку `ready` с целым объектом (уборщик её + пропускает), либо ждёт commit и находит 0 строк; +- прежний уборщик (пометку не ставит) + новые реплики — как до правки. + +В обеих остаётся прежний риск: загрузка, пережившая grace, при откате +транзакции уборки после удачного DELETE объекта; это ограничение в +`REPORT.md`. Порядок сокращает окно смеси: вперёд — сначала реплики +(`make rolling_update`), потом `docker compose up -d --no-deps cleaner`; +откат реплик на версию раньше `87c48b9` (`make rolling_update +COMMIT=<прежний> MIGRATE=0`) — сначала уборщик (его откат или `docker +compose stop cleaner`), потом реплики. Обратная совместимость есть: +новый `mark_ready` на строках, вставленных прежним кодом, работает +(вставка всегда писала `created_at` = `updated_at`). **Bootstrap S3 скрипт не запускает** (design change `s3-storage`, решение 9): новая реплика поднимается с `--no-deps`. Bootstrap, как diff --git a/.claude/rules/logging.md b/.claude/rules/logging.md index fd827d92..d0328fe9 100644 --- a/.claude/rules/logging.md +++ b/.claude/rules/logging.md @@ -169,7 +169,10 @@ paths: ошибок, без значений полей), «Stopped cleaner before startup» — как у API. - `attachment_cleanup_service`: `info` «Removed stale attachment» - (`attachment_id`, `object_key`, `age_seconds`); итог прохода + (`attachment_id`, `object_key`, `age_seconds`) — после commit + транзакции уборки (второй шаг строки: объект и строка под + блокировкой); пометка (первый шаг) и пропуск занятой строки своих + записей не пишут, пропуски видны в `skipped`; итог прохода «Finished cleanup pass» / «Interrupted cleanup pass» (`removed`, `skipped`, `interrupted_by`, `duration_ms`): `warning` при отказе S3 или БД, `info`, если что-то убрано или проход остановлен сигналом, diff --git a/.claude/rules/repo-layer.md b/.claude/rules/repo-layer.md index 8d836de0..fc105292 100644 --- a/.claude/rules/repo-layer.md +++ b/.claude/rules/repo-layer.md @@ -64,7 +64,11 @@ paths: держат), `mark_removing` (пометка к уборке: `updated_at` = время уборщика, позже `created_at`; без миграции, CHECK `updated_after_created` выполняется), `delete_attachment` - (`RETURNING id`, `bool`); DTO — `AttachmentInListDTO`. Статус в этих выражениях — константа + (`RETURNING id`, `bool`); DTO — `AttachmentInListDTO`. Порядок + вызовов — в сервисе (`service-layer.md`), два шага: транзакция + `lock_stale_pending` → `mark_removing`, затем транзакция + `lock_stale_pending` → `delete_original` → `delete_attachment`. + Статус в этих выражениях — константа (`literal(..., literal_execute=True)`), а не параметр: условие частичного индекса `ix_attachments_pending_created_at` планировщик доказывает только по константе, и общий план подготовленного diff --git a/.claude/rules/run-modes.md b/.claude/rules/run-modes.md index b05ba422..b5dfe716 100644 --- a/.claude/rules/run-modes.md +++ b/.claude/rules/run-modes.md @@ -106,9 +106,11 @@ access_log=False)`. Импорты в `src/__main__.py` — внутри `if __n engine и клиента S3; затем обработчики SIGTERM и SIGINT asyncio, `early_stop.disarm()`, «Started cleaner». - Цикл: проход, затем ожидание `[cleaner] interval_seconds` или - сигнала. SIGTERM / SIGINT ставят флаг: доводится текущий шаг строки — - пометка, удаление объекта или строки (не дольше срока шага с БД, 6 с; - флаг проверяется и между шагами), новые не берутся, клиенты закрываются, + сигнала. SIGTERM / SIGINT ставят флаг: доводится до commit или отката + текущий шаг строки — пометка или уборка (объект и строка одной + транзакцией; не дольше срока шага с БД, 6 с, DELETE в S3 внутри него + ≤ 5 с; флаг проверяется и между шагами), новые не берутся, клиенты + закрываются, «Stopped cleaner» и код 0 — раньше `stop_grace_period` 10 с. Сигнал до обработчиков asyncio — ранний обработчик: «Stopped cleaner before startup», код 0. diff --git a/.claude/rules/service-layer.md b/.claude/rules/service-layer.md index 5a4f801c..d4d3943b 100644 --- a/.claude/rules/service-layer.md +++ b/.claude/rules/service-layer.md @@ -97,23 +97,26 @@ paths: (`services/attachment_cleanup.py`), сервис процесса уборщика, а не реплик API: `clean_stale_pending(*, older_than, batch_size, stop_requested)`. Кандидаты — короткая транзакция без блокировки - (keyset), затем каждая строка — три шага (verify W1, design, - «Уточнения apply», п. 16): + (keyset), затем каждая строка — два шага (verify W1 и повторный + verify, design, «Уточнения apply», п. 16 и 21): 1. транзакция пометки: `lock_stale_pending` (`FOR UPDATE SKIP LOCKED`) → `mark_removing` (`updated_at = utcnow()`) → commit; - 2. `delete_original` — вне транзакции, только после подтверждённой - пометки; - 3. транзакция строки: снова `lock_stale_pending` → - `delete_attachment` → commit; строки нет или она занята — - пропуск. + 2. транзакция уборки: снова `lock_stale_pending` → + `delete_original` → `delete_attachment` → commit; строки нет или + она занята — пропуск. Помеченную строку `mark_ready` в `ready` не переводит (`updated_at = - created_at`), поэтому сбой после удаления объекта (откат шага 3, + created_at`), поэтому сбой после удаления объекта (откат шага 2, DELETE, который S3 выполнил после срока) не даёт `ready` без объекта. Не одна транзакция на строку: её откат после удачного DELETE в S3 вернул бы строку непомеченной, и загрузка, пережившая - grace, сделала бы её `ready` без объекта. Объект раньше строки: сбой - между ними оставляет строку без объекта, а не наоборот. Отказ S3 или + grace, сделала бы её `ready` без объекта. DELETE в S3 — под + блокировкой шага 2, а не между транзакциями: реплика до `87c48b9` + пометку не проверяет и иначе сделала бы строку `ready` прямо перед + удалением её объекта. Вызов S3 внутри транзакции ≤ `[s3] + timeout_seconds` (5 с) < `idle_in_transaction_session_timeout` (10 с). + Объект раньше строки: сбой между ними оставляет строку без объекта, а + не наоборот. Отказ S3 или БД прерывает проход (`session_scope` уже записал `warning`), помеченная строка ждёт следующего прохода — пометка ставится заново. `stop_requested()` проверяется перед строкой и между шагами. Итог — diff --git a/.claude/rules/student-tests.md b/.claude/rules/student-tests.md index 02fdee4a..13cd5f2d 100644 --- a/.claude/rules/student-tests.md +++ b/.claude/rules/student-tests.md @@ -128,7 +128,9 @@ paths: `BEFORE UPDATE OF status`, пока строку не уберёт уборщик: на уровне оператора строка не заблокирована, а пометку уборщика (только `updated_at`) `OF status` не задерживает; `undeletable` — как - `outlive`, и удаление строки падает), `clear-fail-attachments`, + `outlive`, и удаление строки падает — в той же транзакции уборки, + где уборщик уже удалил объект: это откат второго шага после удачного + DELETE в S3), `clear-fail-attachments`, `kill-api` / `start-api` (`docker kill` / `docker start` `-api`, ожидание `healthy`); - тесты: `test_upload_with_object_storage_stopped` (+ «Незавершённая @@ -161,7 +163,9 @@ paths: сценарии прежний код уже выполнял. Тесты по замечаниям verify: `test_cleaner_failure_after_object_delete` красный на коде до пометки (201: ждавший `mark_ready` перевёл строку в `ready` после отката - уборщика, объект уже удалён); `test_ready_commit_outcome_unknown` и + уборщика, объект уже удалён; на двухшаговой схеме — пометка, затем + объект и строка одной транзакцией — тест не менялся и проверяет тот + же откат); `test_ready_commit_outcome_unknown` и `test_upload_outlives_grace` на том коде зелёные (ветки были верны) и красные на временных регрессиях — компенсация на любой сбой (объекта нет сразу после 503) и возврат `RuntimeError` (500); diff --git a/AGENTS.md b/AGENTS.md index e73fb7fa..601226ff 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -131,9 +131,10 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore загрузки убирает только уборщик — отдельный сервис `cleaner` на образе API, а не реплики: строки `pending` старше `[cleaner] pending_grace_seconds` (900 с; больше границы живой загрузки 17 с, - иначе уборщик не стартует) под `FOR UPDATE SKIP LOCKED`: сначала - пометка строки (`updated_at`) отдельной транзакцией, затем объект, - затем строка; помеченную строку `mark_ready` в `ready` не переводит, + иначе уборщик не стартует) под `FOR UPDATE SKIP LOCKED`, в два шага: + пометка строки (`updated_at`) отдельной транзакцией, затем объект и + строка одной транзакцией под блокировкой (объект раньше строки); + помеченную строку `mark_ready` в `ready` не переводит, `ready` уборщик не трогает. У уборщика свой пользователь S3 — только чтение и удаление объектов своего bucket, ключи `S3_CLEANER_*` только у него и bootstrap (`docker.md`, `settings.md`). @@ -359,7 +360,7 @@ src/ __main__.py # python -m src: early_stop.install() до импорта приложения → main.main() main.py # FastAPI app: lifespan, middlewares, обработчики ошибок, uvicorn.run cleaner/__main__.py # python -m src.cleaner [--once]: early_stop.install("cleaner") до импорта → main(); неверные настройки — запись без значений и код 2 - cleaner/main.py # уборщик незавершённых загрузок: проверка grace > 2 × request_timeout + s3 timeout (иначе код 2), свой engine и клиент S3, цикл с интервалом, SIGTERM — довести строку и выйти 0, --once — коды 0/1/2 + cleaner/main.py # уборщик незавершённых загрузок: проверка grace > 2 × request_timeout + s3 timeout (иначе код 2), свой engine и клиент S3, цикл с интервалом, SIGTERM — довести текущий шаг строки и выйти 0, --once — коды 0/1/2 config/settings.py # Settings (pydantic-settings), экземпляр settings; [app] instance_id (пусто → hostname) и keep_alive_seconds, [database] pool_size 10 и max_overflow 0 (постоянный пул без переполнения), idle_in_transaction_timeout_ms, [s3] адрес, bucket (валидатор имени), ключи API, регион, сроки, пул и endpoint_url, [idempotency] ttl_seconds, [cleaner] interval_seconds 60, pending_grace_seconds 900, batch_size 100 api/ routers/health.py # /health/live, /health/ready: вне версии, без идентификации @@ -377,7 +378,7 @@ src/ repos/message.py # MESSAGE_COLUMNS с ARRAY(подзапрос attachment_ids по position), вставка связей одной вставкой services/.py # Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем; отправка — ключ, сообщение и связи с вложениями одной транзакцией services/attachment.py # AttachmentService(db_scope, cache, storage): загрузка (проверки → тело со счётчиком в BytesIO, bytes без копии → структура и SHA-256 в потоке → pending → PUT → ready; сбой ready до COMMIT или пропавшая строка — удаление объекта и 503), метаданные, отдача потоком - services/attachment_cleanup.py # AttachmentCleanupService(db_scope, storage): проход уборщика — кандидаты keyset, каждая строка в три шага: блокировка и пометка (commit) → DELETE объекта → блокировка и DELETE строки (commit); отказ S3 или БД прерывает проход, SIGTERM — после текущего шага; CleanupPassDTO + services/attachment_cleanup.py # AttachmentCleanupService(db_scope, storage): проход уборщика — кандидаты keyset, каждая строка в два шага: блокировка и пометка (commit) → блокировка, DELETE объекта и DELETE строки (commit); отказ S3 или БД прерывает проход, SIGTERM — после текущего шага; CleanupPassDTO exceptions/.py # доменные исключения, реэкспорт в __init__.py; storage.py — ObjectStorageUnavailable (503) и StoredObjectMissing; attachment.py — 404, 413, 415, 400 обрыва, 500 пропавшего объекта infra/ early_stop.py # ранний обработчик SIGTERM/SIGINT (только stdlib): до старта сервера — запись «Stopped <процесс> before startup» (API, cleaner) и выход 0; disarm() — первая строка lifespan; write_record — запись мимо structlog diff --git a/PLAN.md b/PLAN.md index 8397f1d2..0121f846 100644 --- a/PLAN.md +++ b/PLAN.md @@ -799,7 +799,7 @@ design, «Уточнения apply», пп. 10–15): `mark_ready` → `None` — 503 вместо 500. 2. **Уборщик — сервис `cleaner`, `python -m src.cleaner`** (решение 2): - свой engine (пул 1) и клиент S3, цикл с интервалом, `--once`; - - SIGTERM — довести строку и выйти с кодом 0; + - SIGTERM — довести текущий шаг строки и выйти с кодом 0; - healthcheck образа выключен; - в консоли (`make run_dev`) уборщика нет. 3. **Проход** (решение 3): строка под `FOR UPDATE SKIP LOCKED` → DELETE @@ -807,7 +807,8 @@ design, «Уточнения apply», пп. 10–15): `mark_ready` загрузки, пережившей grace. Остаток риска: API заморожен дольше grace посреди PUT — объект без строки, его находит сверка трека 2. После verify — пометка строки отдельной транзакцией до - DELETE объекта (решение 18 ниже). + DELETE объекта (решение 18 ниже), после повторного — объект и строка + одной транзакцией под блокировкой (решение 23). 4. **Grace 900 с, интервал 60 с, выборка 100** (решение 4): - граница живой загрузки от строки до `ready`: B = 2 × 6 + 5 = 17 с, запас ×50; @@ -857,7 +858,8 @@ apply»): общий план asyncpg иначе не взял бы частичный индекс. План — `Index Scan` по `ix_attachments_pending_created_at`. 14. **SIGTERM посреди прохода** — `stop_requested` у - `clean_stale_pending`: строка доводится, новые не берутся. + `clean_stale_pending`: текущий шаг строки доводится до commit или + отката, новые не начинаются (после решения 19). 15. **Неверные настройки уборщика** — запись без значений полей и код 2, а не traceback. 16. **`entrypoint` у сервиса `cleaner`**, чтобы `docker compose run @@ -879,7 +881,8 @@ design, «Уточнения apply», п. 16–20; tasks, группа 11): уборщик) и объект без строки, если зомби дописал объект после уборки, а компенсация не удалась. 19. **SIGTERM уборщика — между шагами строки**: три шага удлинили бы - худшую остановку до 17 с; доводится только текущий шаг (≤ 6 с). + худшую остановку до 17 с (после решения 23 шагов два — до 12 с); + доводится только текущий шаг (≤ 6 с). Требование `graceful-shutdown` «Остановка уборщика» уточнено. 20. **W2, W3 — режимы hook `commit` и `outlive`** и тесты веток «исход COMMIT неизвестен» и «строку убрал уборщик до `ready`»; W1 — режим @@ -891,6 +894,28 @@ design, «Уточнения apply», п. 16–20; tasks, группа 11): 22. **W4 и S1** — evidence «Отказ S3 во время прохода» с закоммиченного кода; `docker.md` — `entrypoint` уборщика. +Приняты 2026-10-21 в правках по повторному verify (решения основной +сессии; design, «Уточнения apply», п. 21; tasks, группа 12): + +23. **W1 повторной проверки — два шага вместо трёх**: транзакция + пометки, затем объект и строка одной транзакцией под блокировкой + (как в `f2dc0b3`, но на помеченной строке). В решении 18 объект + удалялся без блокировки, и реплика до `87c48b9` успевала сделать + строку `ready` прямо перед удалением объекта — смесь «новый уборщик + + прежние реплики» была хуже, чем до правки. Теперь обе смеси не хуже, + чем до правки (проба блокировок — design, п. 21), остаётся только + откат транзакции уборки после удачного DELETE. Цена — вызов S3 внутри + транзакции (≤ 5 с < `idle_in_transaction_session_timeout` 10 с). + Решения 18 и 19 в части «три шага» заменены этим. +24. **Порядок обновления**: вперёд — сначала реплики (`make + rolling_update`), потом `docker compose up -d --no-deps cleaner`; + откат реплик на версию раньше `87c48b9` — сначала уборщик + (`balancer.md`, `REPORT.md`). +25. **Тесты 11.x не менялись**: `undeletable` на двухшаговой схеме роняет + DELETE строки в той же транзакции, что DELETE объекта, — это тот же + откат после удачного DELETE в S3; красный прогон на `f2dc0b3` в силе. + Требования `graceful-shutdown` и `storage-consistency` не менялись. + #### Вопросы 1. Как перенести секреты уборщика `S3_CLEANER_ACCESS_KEY` и diff --git a/REPORT.md b/REPORT.md index e9559a1f..771408ac 100644 --- a/REPORT.md +++ b/REPORT.md @@ -319,20 +319,20 @@ PostgreSQL **до** записи — строка `pending` с `object_key` фи выбирает строки `pending` старше `[cleaner] pending_grace_seconds` (900 с) выборками по 100 (keyset по `(created_at, id)`, частичный индекс `ix_attachments_pending_created_at` — план в -`evidence/migrations/pending-index.md`) и каждую убирает в три шага -(после verify, `87c48b9`): +`evidence/migrations/pending-index.md`) и каждую убирает в два шага +(после двух verify): 1. транзакция пометки: `SELECT … FOR UPDATE SKIP LOCKED` той же строки (всё ещё `pending` и старше порога; нет — пропуск), `updated_at = now()` уборщика, commit; -2. DELETE объекта ключом уборщика, вне транзакции (отсутствие объекта — - тоже 204); -3. транзакция строки: та же блокировка, DELETE строки, commit. +2. транзакция уборки: та же блокировка (нет строки или занята — + пропуск), DELETE объекта ключом уборщика (отсутствие объекта — тоже + 204), DELETE строки, commit. -Объект удаляется раньше строки: сбой между шагами оставляет строку без +Объект удаляется раньше строки: сбой между ними оставляет строку без объекта (следующий проход её доуберёт, пометка ставится заново), а не объект без строки. Строки `ready` выборка не видит никогда. SIGTERM -доводит только текущий шаг (≤ 6 с), между шагами уборщик останавливается -сам. +доводит только текущий шаг до commit или отката (≤ 6 с), между шагами +уборщик останавливается сам. **Зачем блокировка.** Загрузка короче grace, но процесс API, замороженный дольше grace (`docker pause`, пауза ВМ), после разморозки дойдёт до @@ -352,9 +352,20 @@ DELETE, который S3 выполнил после срока вызова, пометка зафиксирована до DELETE объекта. Помеченная строка `ready` уже не станет: загрузка получает 503 и удаляет свой объект, уборку доводит следующий проход (`test_cleaner_failure_after_object_delete`). Миграции -нет, CHECK `updated_at >= created_at` выполняется. Блокировку держат -только две короткие транзакции; DELETE в S3 — между ними, в своём пуле -уборщика из одного соединения. +нет, CHECK `updated_at >= created_at` выполняется. + +**Зачем DELETE объекта под блокировкой** (замечание W1 повторного +verify). В первой редакции пометки объект удалялся между транзакциями, +без блокировки. Реплика до `87c48b9` пометку не проверяет: она успевала +сделать строку `ready` между commit пометки и DELETE объекта, и уборщик +удалял объект готового вложения без всякого сбоя. Теперь объект и строка +удаляются одной транзакцией под блокировкой: такая реплика либо успела +раньше (строка `ready` с целым объектом, уборщик её не находит), либо ждёт +commit и находит 0 строк (проба блокировок — design, «Уточнения apply», +п. 21). Цена — вызов S3 внутри транзакции: ≤ 5 с (`[s3] +timeout_seconds`) внутри срока шага 6 с, меньше +`idle_in_transaction_session_timeout` 10 с; пул уборщика свой, из одного +соединения. **Grace period и его обоснование.** Граница живой загрузки B — от записи `created_at` строки до фиксации `ready`: tx1 ≤ @@ -381,13 +392,14 @@ DELETE, который S3 выполнил после срока вызова, основание удалять) и оставлено для глубокой сверки трека 2. **Отказы хранилищ в уборщике.** S3 недоступен, не ответил, отказал в -доступе или bucket нет — транзакция строки откатывается, проход -прерывается на первой строке (`warning`), следующий — через интервал. +доступе или bucket нет — транзакция уборки откатывается, строка остаётся +`pending` и помеченной, проход прерывается на первой строке (`warning`), +следующий — через интервал (пометка ставится заново). PostgreSQL недоступен — проход пропускается (`warning`). Непредвиденная ошибка — `error` с traceback, процесс живёт. Перезапуск не нужен: у клиента S3 нет повторов, пул PostgreSQL — с `pool_pre_ping` -(`test_cleaner_survives_outages`). SIGTERM: текущая строка доводится, -выход с кодом 0 за ~0,6 с. +(`test_cleaner_survives_outages`). SIGTERM: текущий шаг уборки доводится +до commit или отката, новые не начинаются, выход с кодом 0 за ~0,6 с. **Доказательства**: `evidence/attachments/consistency.md` (рабочий стенд: S3 заморожен и сбой фиксации `ready` → 503, строки не видны, @@ -605,14 +617,24 @@ S3 (change `s3-storage`): сверка bucket и БД (трек 2). `ready` без объекта при этом не возникает: уборщик помечает строку до удаления объекта, а помеченную `mark_ready` в `ready` не переводит. -- **Окно `make rolling_update` для пометки.** Реплики прежней версии - (`f2dc0b3` и раньше) пометку не проверяют, а скрипт замены уборщика не - пересоздаёт (прежний не помечает). Пока замена не закончена и не - выполнен `docker compose up -d --no-deps cleaner`, для загрузки, - пережившей grace, остаётся прежний риск: откат транзакции уборщика - после удачного DELETE в S3 даёт `ready` без объекта. Нужно совпадение - зомби дольше 15 мин и сбоя в окне меньше секунды. Смешанные версии - друг другу не мешают: новый `mark_ready` работает на строках прежних +- **Смесь версий уборщика и реплик.** Реплики до `87c48b9` (`f2dc0b3` + и раньше) пометку не проверяют, а прежний уборщик её не ставит; + `make rolling_update` уборщика не пересоздаёт. Обе смеси не хуже, чем + до правки: + - новый уборщик + прежние реплики: объект и строка удаляются одной + транзакцией под блокировкой, прежний `mark_ready` либо делает строку + `ready` с целым объектом (уборщик её пропускает), либо ждёт commit и + находит 0 строк; + - прежний уборщик + новые реплики — поведение до правки. + + В обеих для загрузки, пережившей grace, остаётся прежний риск: откат + транзакции уборки после удачного DELETE в S3 даёт `ready` без объекта. + Нужно совпадение зомби дольше 15 мин и сбоя в окне меньше секунды. + Порядок обновления сокращает окно: вперёд — сначала реплики (`make + rolling_update`), потом `docker compose up -d --no-deps cleaner`; + откат реплик на версию раньше `87c48b9` — сначала уборщик (его откат + или `docker compose stop cleaner`), потом `make rolling_update + COMMIT=… MIGRATE=0`. Новый `mark_ready` работает на строках прежних реплик (вставка всегда писала `created_at` = `updated_at`). - **Проверка grace — по настройкам уборщика.** `config.toml` у API и уборщика общий, но подмена сроков окружением только у API diff --git a/openspec/changes/upload-consistency/design.md b/openspec/changes/upload-consistency/design.md index 3a5c8871..a0dc44c8 100644 --- a/openspec/changes/upload-consistency/design.md +++ b/openspec/changes/upload-consistency/design.md @@ -171,8 +171,10 @@ COMMIT. Отвергнута: вложение могло стать `ready`, и - `src/infra/early_stop.py` получает имя процесса для записи «Stopped … before startup»; у API текст прежний; - после старта цикла — обработчики asyncio. SIGTERM и SIGINT ставят - флаг, текущая строка доводится (не дольше срока шага с БД, 6 с), и - процесс выходит с кодом 0 и записью «Stopped cleaner»; + флаг, текущий шаг уборки строки доводится до commit или отката (не + дольше срока шага с БД, 6 с), новые шаги не начинаются, и процесс + выходит с кодом 0 и записью «Stopped cleaner» («Уточнения apply», + п. 16 и 21); - `stop_grace_period` 10 с, как у `api`. - Healthcheck образа (HTTP) в сервисе выключен (`healthcheck: disable: true`). Живость видна по журналу: старт, проходы, отказы. Уборщик ни @@ -204,20 +206,21 @@ cron-контейнер. Отвергнуты: ещё один образ, S3 и (created_at, id) > (:after) ORDER BY created_at, id LIMIT :batch_size`. Это keyset, как у истории, по частичному индексу (решение 6). Занятая строка не возвращает проход к началу. -3. Каждый кандидат — три шага (после verify W1, «Уточнения apply», - п. 16; было — одна транзакция с DELETE объекта внутри): +3. Каждый кандидат — два шага (после verify W1 и повторного verify, + «Уточнения apply», п. 16 и 21; было — одна транзакция с DELETE + объекта внутри, без пометки): 1. транзакция пометки: `SELECT … WHERE id = :id AND status = 'pending' AND created_at < :older_than FOR UPDATE SKIP LOCKED` (нет строки — её уже убрали, она стала `ready` или её держит другой процесс: пропуск) → `UPDATE … SET updated_at = utcnow()` → commit; - 2. `storage.delete(object_key)` вне транзакции: 204 и для - отсутствующего объекта; - 3. транзакция строки: та же блокировка → `DELETE FROM attachments - WHERE id = :id` → commit. + 2. транзакция уборки: та же блокировка (нет строки или занята — + пропуск) → `storage.delete(object_key)` (204 и для отсутствующего + объекта) → `DELETE FROM attachments WHERE id = :id` → commit. - Отказ S3 прерывает проход: помеченная строка остаётся `pending`, - следующий проход ставит пометку заново (решение 5). + Отказ S3 прерывает проход: шаг 2 откатывается, помеченная строка + остаётся `pending`, следующий проход ставит пометку заново (решение + 5). 4. Итог — DTO: сколько убрано, сколько пропущено, причина прерывания, длительность. @@ -250,14 +253,26 @@ grace, после разморозки дойдёт до `mark_ready`. Без б `updated_at = created_at`. Вставка пишет оба поля одним значением (`now`), а пометка — время уборщика, оно позже порога прохода и тем более `created_at`. Помеченная строка `ready` уже не станет, и любой -исход шагов 2–3 оставляет её `pending`: загрузка получает `None` (503 и +исход шага 2 оставляет её `pending`: загрузка получает `None` (503 и компенсация), уборку доводит следующий проход. Миграции нет, CHECK `updated_after_created` выполняется. -Блокировку и соединение уборщика держат только короткие транзакции -пометки и удаления строки; DELETE в S3 — между ними, вне транзакции. -Пул у уборщика свой, на реплики это не влияет. Сроки шага: `[s3] -timeout_seconds` (5) и `[database] request_timeout_seconds` (6) < +Зачем DELETE в S3 под блокировкой шага 2, а не между транзакциями +(повторный verify W1). Прежний `mark_ready` (реплики до `87c48b9`) +пометку не проверяет. Если бы объект удалялся после commit пометки без +блокировки, такая реплика могла бы сделать строку `ready` между commit +пометки и DELETE объекта, а уборщик затем удалил бы объект: `ready` без +объекта без всякого сбоя. Под блокировкой шага 2 прежний `mark_ready` +либо успел раньше (строка `ready` с целым объектом, шаг 2 её не +находит), либо ждёт commit шага 2 и находит 0 строк. Остаётся только +риск до правки: откат шага 2 после удачного DELETE (проба — «Уточнения +apply», п. 21). + +Цена — вызов S3 внутри транзакции, как в первой версии: блокировку и +соединение уборщика держат транзакция пометки и транзакция уборки, в +ней DELETE в S3 не дольше `[s3] timeout_seconds` (5 с). Пул у уборщика +свой, на реплики это не влияет. Сроки шага: `[s3] timeout_seconds` (5) +внутри `[database] request_timeout_seconds` (6) < `idle_in_transaction_session_timeout` (10 с). Остаток риска, назван в спеке и `REPORT.md`. Процесс API заморожен @@ -265,9 +280,9 @@ timeout_seconds` (5) и `[database] request_timeout_seconds` (6) < S3 принял тело. Компенсации при этом нет: PUT для API завершился ошибкой по сроку. Или PUT прошёл, `mark_ready` получил `None`, а удаление при компенсации не удалось. Объект остаётся без строки, его -находит только сверка списком bucket (трек 2). Второй остаток — окно -`make rolling_update` (п. 16): реплики прежней версии пометку не -проверяют. +находит только сверка списком bucket (трек 2). Второй остаток — смесь +версий (п. 16 и 21): реплики до `87c48b9` пометку не проверяют, и для их +загрузок остаётся риск до правки — откат шага 2 после удачного DELETE. *Альтернатива:* без блокировки, условие возраста в `mark_ready` (`AND created_at > :deadline`). Отвергнута: API пришлось бы знать grace @@ -326,9 +341,10 @@ B = 2 × 6 + 5 = 17 с. Тело и проверка изображения ид ### 5. Отказы хранилищ в уборщике - S3 недоступен, не ответил, отказал в доступе или bucket нет - (`ObjectStorageUnavailable`): транзакция строки откатывается, проход + (`ObjectStorageUnavailable`): транзакция уборки (шаг 2 решения 3) + откатывается, строка остаётся `pending` и помеченной, проход прерывается на первой строке, в журнале `warning` с причиной. Дальше - — через интервал. Удалённый bucket SeaweedFS отдаёт `NoSuchBucket` + — через интервал, пометка ставится заново. Удалённый bucket SeaweedFS отдаёт `NoSuchBucket` (проба), клиент переводит его в 503, строки остаются. Запись `KNOWN_ISSUES.md` о bootstrap после удаления bucket — трек 2. - PostgreSQL недоступен (`ServiceUnavailable` общего контекста сессии, @@ -589,24 +605,32 @@ Evidence (с закоммиченного кода): названо прямо. - [`ready` без объекта при откате транзакции уборщика после удачного DELETE в S3 (verify W1)] → закрыто пометкой строки отдельной - транзакцией до DELETE объекта (решение 3, «Уточнения apply», п. 16). - Остаток — окно `make rolling_update`: реплики прежней версии - пометку не проверяют, прежний уборщик её не ставит. Оно длится до - конца замены и `docker compose up -d --no-deps cleaner`, нужен ещё и - зомби дольше grace — ограничение в `REPORT.md`. -- [Три шага на строку вместо одной транзакции: SIGTERM посреди строки - мог бы ждать 6 + 5 + 6 с при зависших хранилищах] → флаг остановки - проверяется и между шагами, доводится только текущий шаг (≤ 6 с < + транзакцией до DELETE объекта (решение 3, «Уточнения apply», п. 16 и + 21) на стенде одной версии. Смесь версий не хуже, чем до правки: + новый уборщик с репликами до `87c48b9` (пометку не проверяют) и + прежний уборщик с новыми репликами (пометку не ставит) оставляют + только прежний риск — откат транзакции уборки после удачного DELETE, + для загрузки-зомби дольше grace. Порядок обновления это окно + сокращает: вперёд — сначала реплики (`make rolling_update`), потом + `docker compose up -d --no-deps cleaner`; откат реплик на версию + раньше `87c48b9` — сначала уборщик (`balancer.md`). Ограничение в + `REPORT.md`. +- [Два шага на строку вместо одной транзакции: SIGTERM посреди строки + мог бы ждать 6 + 6 с при зависших хранилищах] → флаг остановки + проверяется и между шагами, доводится только текущий шаг (≤ 6 с срока + шага, DELETE в S3 внутри него ≤ 5 с, плюс закрытие соединения — меньше 10 с `stop_grace_period`). Требование `graceful-shutdown` уточнено. - [Компенсация добавляет до 5 с к ответу 503, если S3 стал медленным после удачного PUT] → только ветка сбоя tx2. Худший путь загрузки и так длиннее `timeout server` HAProxy (`attachments`, Risks). Пересмотр цепочки — `upload-memory`. -- [Транзакции уборщика держат блокировку строки] → только короткие - транзакции пометки и удаления строки и только строки старше grace; - DELETE в S3 — между ними, вне транзакции (после verify W1). - `mark_ready` зомби-загрузки подождёт — это и нужно. Пул уборщика свой - (1 соединение). +- [Транзакции уборщика держат блокировку строки, транзакция уборки — и + на время DELETE в S3] → только строки старше grace; транзакция + пометки короткая, транзакция уборки — не дольше срока шага (6 с, DELETE + в S3 ≤ 5 с) < `idle_in_transaction_session_timeout` (10 с). + `mark_ready` зомби-загрузки подождёт — это и нужно: так и прежняя + реплика не делает `ready` строку, объект которой удаляется. Пул + уборщика свой (1 соединение). - [Долгий отказ S3 копит строки `pending`: каждая попытка загрузки — одна строка] → после возврата S3 уборщик убирает их выборками по 100 через индекс. Стоимость обхода — трек 2. @@ -623,7 +647,9 @@ Evidence (с закоммиченного кода): `REPORT.md`. - [После `make rolling_update` уборщик на прежнем образе] → схема только расширяется, прежний код уборщика корректен. Обновление — - `docker compose up -d --no-deps cleaner` (`balancer.md`). + `docker compose up -d --no-deps cleaner` после замены реплик; при + откате реплик на версию раньше `87c48b9` уборщик откатывается первым + (`balancer.md`). - [Уборщик на стенде отказов зашумит прежние тесты] → разобрано в решении 10. Если `test_pool_keeps_connections` поймает шум, его калибровка это назовёт. Тогда в apply — пауза уборщика hook-ом на окно @@ -654,9 +680,11 @@ Evidence (с закоммиченного кода): s3-bootstrap cleaner`. Bootstrap только добавляет пользователя и права у API не забирает (`balancer.md`). -Откат — `make rolling_update COMMIT=d9d44c5 MIGRATE=0` и `docker compose -stop cleaner`. Индекс и пользователь `cleaner` остаются, прежнему коду -они не мешают. Строки `pending` снова копятся до возврата вперёд. +Откат — сначала `docker compose stop cleaner`, затем `make +rolling_update COMMIT=d9d44c5 MIGRATE=0` (уборщик раньше реплик: +«Уточнения apply», п. 21). Индекс и пользователь `cleaner` остаются, +прежнему коду они не мешают. Строки `pending` снова копятся до возврата +вперёд. ## Open Questions @@ -707,8 +735,9 @@ stop cleaner`. Индекс и пользователь `cleaner` остаютс NOT EXISTS …` между `COMMIT` прежних ревизий и `BEGIN` записи версии. 4. **Остановка посреди прохода.** У `clean_stale_pending` параметр `stop_requested` (по умолчанию «никогда»): проверяется перед каждой - строкой, и по SIGTERM проход доводит текущую строку и не берёт новые - (спек `graceful-shutdown`, «Остановка уборщика»). Причина в итоге — + строкой и между шагами строки (п. 16 и 21), и по SIGTERM проход + доводит текущий шаг до commit или отката и новых не начинает (спек + `graceful-shutdown`, «Остановка уборщика»). Причина в итоге — `interrupted_by="stop"`, запись прохода `info`, `--once` — код 0. Флаг цикла один проверял бы только между проходами, а проход из многих выборок длиннее 10 с. @@ -787,9 +816,12 @@ stop cleaner`. Индекс и пользователь `cleaner` остаютс основной сессии, tasks, группа 11): 16. **W1 закрыт кодом: пометка строки до удаления объекта** (решение 3, - Risks). Уборщик: `lock_stale_pending` → `mark_removing` (`updated_at - = utcnow()`) → commit; `delete_original`; `lock_stale_pending` → - `delete_attachment` → commit. `mark_ready` — `AND updated_at = + Risks). Уборщик (в редакции п. 21 — два шага): `lock_stale_pending` + → `mark_removing` (`updated_at = utcnow()`) → commit; + `lock_stale_pending` → `delete_original` → `delete_attachment` → + commit. В первой редакции `delete_original` шёл между транзакциями, + вне блокировки — повторный verify нашёл в этом W1 смеси версий + (п. 21). `mark_ready` — `AND updated_at = created_at`, помеченная строка — `None`, то есть прежняя ветка «строку убрал уборщик» (503 и компенсация). Проверено: - вставка `pending` пишет оба поля одним `now` — и в текущем коде, и @@ -799,16 +831,17 @@ stop cleaner`. Индекс и пользователь `cleaner` остаютс older_than`, а `utcnow()` уборщика позже `older_than`; - повтор после сбоя между транзакциями идемпотентен — пометка ставится заново, следующий проход доводит строку; - - окно `make rolling_update`: реплики прежней версии (`f2dc0b3`) - условия не знают, а скрипт уборщика не пересоздаёт (прежний - уборщик не помечает). До конца замены и `docker compose up -d - --no-deps cleaner` остаётся прежний риск W1, это ограничение - (`balancer.md`, `REPORT.md`). Смешанные версии друг другу не - мешают: прежний уборщик с новыми репликами — поведение до правки, - новый уборщик с прежними репликами — тоже. + - смесь версий во время `make rolling_update` и до пересоздания + уборщика: реплики до `87c48b9` (`f2dc0b3` и раньше) условия + пометки не знают, а скрипт уборщика не пересоздаёт (прежний + уборщик не помечает). Обе смеси не хуже, чем до правки: остаётся + только прежний риск W1 — откат транзакции уборки после удачного + DELETE, для загрузки-зомби дольше grace. Это ограничение + (`balancer.md`, `REPORT.md`); разбор смесей и порядок обновления — + п. 21. - Три шага вместо одной транзакции удлиняют худший SIGTERM посреди - строки до 6 + 5 + 6 с при зависших хранилищах. Поэтому + Два шага вместо одной транзакции удлиняют худший SIGTERM посреди + строки до 6 + 6 с при зависших хранилищах. Поэтому `stop_requested()` проверяется и между шагами (доводится только текущий, ≤ 6 с < 10 с), а требование `graceful-shutdown` «Остановка уборщика» уточнено: «довести текущий шаг уборки … новых шагов не @@ -857,3 +890,83 @@ stop cleaner`. Индекс и пользователь `cleaner` остаютс этом коде PASS, его шаги правка не меняет. 20. **S1** — `docker.md`, раздел «Уборщик»: `entrypoint`, как в `docker-compose.yml`, и почему не `command` (п. 6). + +Правки по повторному verify 2026-10-21 (HEAD `6551839`; 0 CRITICAL, 1 +WARNING, 2 SUGGESTION; решения основной сессии, tasks, группа 12): + +21. **W1 повторной проверки: удаление объекта и строки — одна + транзакция под блокировкой** (решение 3, Risks). В редакции п. 16 + уборщик удалял объект между транзакциями, без блокировки. Прежний + `mark_ready` (`f2dc0b3`, `5b42bd2`, `d9d44c5`) пометку не проверяет: + ждавший блокировку пометки или пришедший между шагами делал строку + `ready`, затем уборщик удалял объект, а шаг строки её пропускал — + `ready` без объекта без всякого сбоя, хуже, чем до правки. Теперь + шагов два: транзакция пометки (`lock_stale_pending` → + `mark_removing` → commit) и транзакция уборки (`lock_stale_pending` + → `delete_original` → `delete_attachment` → commit; строки нет или + она занята — пропуск). `stop_requested()` — перед строкой и между + шагами. + + Проба блокировок (`probe_two_step.sh` по образцу пробы verify, + одноразовый `postgres:18.6-trixie` на tmpfs с `--rm`, рабочая база не + участвует; объект — файл, его удаление вне транзакции, как вызов S3): + + | Уборщик | `mark_ready` | Момент | Итог | + |---|---|---|---| + | новый | новый | ждёт блокировку пометки | 0 строк; шаг 2 убрал объект и строку | + | новый | новый | между шагами | 0 строк; шаг 2 убрал обе | + | новый | новый | во время шага 2, COMMIT | 0 строк; ни строки, ни объекта | + | новый | новый | во время шага 2, ROLLBACK после DELETE объекта | 0 строк; строка `pending`, помечена, объекта нет — доводит следующий проход | + | новый | прежний | ждёт блокировку пометки | 1 строка: `ready` с целым объектом; шаг 2 — 0 строк, объект не тронут | + | новый | прежний | между шагами | то же: `ready` с объектом, шаг 2 пропускает | + | новый | прежний | во время шага 2, COMMIT | 0 строк; ни строки, ни объекта | + | новый | прежний | во время шага 2, ROLLBACK после DELETE объекта | 1 строка: `ready` без объекта — прежний риск | + | прежний | новый / прежний | во время транзакции, COMMIT | 0 строк; ни строки, ни объекта | + | прежний | новый / прежний | во время транзакции, ROLLBACK | `ready` без объекта — риск до правки | + + Итог по смесям: + - стенд одной версии: `ready` без объекта не появляется ни при каком + порядке — ни при откате шага 2 после удачного DELETE, ни при + DELETE, выполненном S3 после срока: строка остаётся помеченной, а + новый `mark_ready` её не переводит; + - новый уборщик + прежние реплики: не хуже, чем до правки. Прежний + `mark_ready`, ждавший блокировку пометки или пришедший между + шагами, делает строку `ready` с ещё целым объектом, и шаг 2 её + пропускает; пришедший во время шага 2 после COMMIT находит 0 + строк. Остаётся только прежний риск — откат шага 2 после удачного + DELETE; + - прежний уборщик + новые реплики: как до правки (пометки нет, риск — + тот же откат). + + Порядок обновления сокращает окно смеси (`balancer.md`, `REPORT.md`): + вперёд — сначала реплики (`make rolling_update`), потом `docker + compose up -d --no-deps cleaner`; откат реплик на версию раньше + `87c48b9` — сначала уборщик (его откат или `docker compose stop + cleaner`), потом реплики. + + SIGTERM: худший путь — текущий шаг, не дольше 6 с срока шага (DELETE + в S3 внутри него ≤ 5 с), плюс закрытие соединения — меньше 10 с + `stop_grace_period`. Вызов S3 внутри транзакции ≤ 5 с < + `idle_in_transaction_session_timeout` (10 с). Требования + `graceful-shutdown` и `storage-consistency` не меняются: «текущий + шаг» и порядок «пометка → объект → метаданные» верны и для двух + шагов, ограничение «реплики прежней версии пометку не проверяют» — + тоже. + + Тесты 11.x на двухшаговой схеме проверяют то же, тексты не менялись: + - `test_cleaner_failure_after_object_delete` (`undeletable`): DELETE + строки падает в той же транзакции, что DELETE объекта, — это и + есть «откат шага 2 после удачного DELETE в S3», свойство W1. + Строка остаётся помеченной, ждавший `mark_ready` получает 0 строк + (503 и компенсация), после снятия триггера следующий проход + доводит уборку. Тест не менялся, его красный прогон на `f2dc0b3` + (п. 16) в силе; + - `test_upload_outlives_grace` (`outlive`): шаг 2 убирает объект и + строку одной транзакцией, ждавший `mark_ready` — 0 строк, 503; + - `test_ready_commit_outcome_unknown` (`commit`): уборщика не + касается. + + Полный `make failure_checks` на этом коде (рабочее дерево поверх + `6551839`) — код 0, 32 passed за 235 с, в том числе все три теста + 11.x; журнал PostgreSQL стенда — crash markers 0; стенд отказов и + его volumes удалены. diff --git a/openspec/changes/upload-consistency/tasks.md b/openspec/changes/upload-consistency/tasks.md index 742c1641..9ec7c0a6 100644 --- a/openspec/changes/upload-consistency/tasks.md +++ b/openspec/changes/upload-consistency/tasks.md @@ -401,3 +401,57 @@ Verify 2026-10-21: 0 CRITICAL, 4 WARNING, 1 SUGGESTION; решения `evidence/tests/failure-checks.md` и чисел в `evidence/tests/` и `REPORT.md`; `REPORT.md` — порядок уборки с пометкой и остаточный риск, новые проверки, строка W4; строка этапа 3 `PLAN.md`. + +## 12. Замечания повторной проверки + +Повторный verify 2026-10-21 (HEAD `6551839`): 0 CRITICAL, 1 WARNING, 2 +SUGGESTION; решения основной сессии — design, «Уточнения apply», п. 21. +Изменённый текст требования или сценария правится и в дельте, и в +основном спеке дословно. + +- [x] 12.1 W1, «новый уборщик + прежние реплики хуже, чем до правки» — + кодом: `AttachmentCleanupService._remove` в два шага — транзакция + пометки (`lock_stale_pending` → `mark_removing` → commit), затем одна + транзакция под блокировкой (`lock_stale_pending` → `delete_original` → + `delete_attachment` → commit); строки нет или она занята — пропуск; + `stop_requested()` — перед строкой и между шагами. + + Проверка: + - проба блокировок на одноразовом PostgreSQL (по образцу + `probe_mark.sh`, без рабочей базы): новый `mark_ready` и прежний (как + в `f2dc0b3`) с новым уборщиком — «ждёт блокировку пометки», «между + шагами», «пришёл во время шага 2», откат шага 2 после DELETE объекта; + прежний уборщик с новым `mark_ready` — как до правки; + - тесты 11.x (`test_cleaner_failure_after_object_delete`, + `test_upload_outlives_grace`, `test_ready_commit_outcome_unknown`) + зелёные на новом коде; что проверяет тест W1 на двухшаговой схеме — + в design; если тест меняется — красный прогон на `f2dc0b3` повторно; + - `make lint`. +- [x] 12.2 Текст W1: окно `make rolling_update` и смеси версий по итогу + 12.1 — design («Уточнения apply», п. 16, Risks), `balancer.md`, + `REPORT.md`, требование «Безопасность уборки» (если формулировка уже + не верна); порядок обновления — вперёд сначала реплики, потом `docker + compose up -d --no-deps cleaner`, откат реплик на версию раньше + `87c48b9` — сначала уборщик. Трёхшаговая схема заменена двухшаговой: + `service-layer.md`, `repo-layer.md`, `logging.md`, `run-modes.md`, + `student-tests.md`, AGENTS.md, design, `REPORT.md`, docstring. + Проверка: `grep` «три шага», «вне транзакции» и «шаг 3» по правилам, + AGENTS.md, design, `REPORT.md` и `src/` — только верные упоминания. +- [x] 12.3 S1: «текущая строка доводится» и «транзакция строки + откатывается» — по новой схеме: `REPORT.md`, design (решения 2 и 5), + docstring `attachment_cleanup.py`, комментарий `src/cleaner/main.py`. + Проверка: `grep` этих формулировок пуст. +- [x] 12.4 Проверки до коммита: `make lint`, `make check`, `openspec + validate upload-consistency --type change --strict`, `openspec + validate --specs`, полный `make failure_checks` (код 0, сводка + PostgreSQL без признаков аварии); на рабочем стенде после `make + rolling_update` и `docker compose up -d --no-deps cleaner` — `make + test`, `make student_test` через LB, `driver.py --port + upload-consistency` (код 0). +- [ ] 12.5 После коммита основной сессии: S2 — `evidence/tests/ + student-test-lb.md` (8 сценариев `storage-consistency`, а не 9); + пересъёмка `evidence/tests/failure-checks.md` и раздела 7 + `evidence/attachments/cleaner-process.md` с нового commit; числа в + `REPORT.md` и `PLAN.md`. Проверка: `grep` секретов по `evidence/` + (значения не печатаются), `make lint`, `make check`, `openspec validate + upload-consistency --type change --strict`. diff --git a/src/cleaner/main.py b/src/cleaner/main.py index f721f46d..d3b34a3b 100644 --- a/src/cleaner/main.py +++ b/src/cleaner/main.py @@ -91,7 +91,8 @@ async def run(*, once: bool) -> int: loop = asyncio.get_running_loop() for signum in (signal.SIGTERM, signal.SIGINT): loop.add_signal_handler(signum, stop.set) - # дальше сигналы обрабатывает цикл: текущая строка доводится + # дальше сигналы обрабатывает цикл: текущий шаг уборки доводится до + # commit или отката, новые не начинаются early_stop.disarm() engine = create_engine(settings.database) diff --git a/src/core/services/attachment_cleanup.py b/src/core/services/attachment_cleanup.py index d582d7d1..a7888dc8 100644 --- a/src/core/services/attachment_cleanup.py +++ b/src/core/services/attachment_cleanup.py @@ -2,11 +2,12 @@ решения 3 и 5). Сервис процесса уборщика (`src/cleaner/`), а не реплик API. Строка -`pending` старше grace: блокировка `FOR UPDATE SKIP LOCKED` → пометка -(`updated_at`) → commit → удаление объекта → блокировка → удаление -строки → commit. Метаданные удаляются последними: объекта без строки -уборка не оставляет. Строки `ready` выборка не видит, а помеченную -строку `mark_ready` в `ready` не переводит («Уточнения apply», п. 16). +`pending` старше grace, два шага: блокировка `FOR UPDATE SKIP LOCKED` → +пометка (`updated_at`) → commit; та же блокировка → удаление объекта → +удаление строки → commit. Метаданные удаляются последними: объекта без +строки уборка не оставляет. Строки `ready` выборка не видит, а +помеченную строку `mark_ready` в `ready` не переводит («Уточнения +apply», п. 16 и 21). """ import time @@ -59,10 +60,11 @@ class AttachmentCleanupService: Кандидаты — выборками по `batch_size` (keyset по `(created_at, id)`, без блокировки), затем каждая строка отдельно. Отказ S3 прерывает проход на первой же строке, отказ PostgreSQL — тоже: в - обоих случаях строка остаётся, следующий проход — через интервал. - `stop_requested()` проверяется перед каждой строкой: по SIGTERM - текущая строка доводится, новые не берутся (спек - `graceful-shutdown`, «Остановка уборщика»). + обоих случаях строка остаётся (после пометки — помеченной), + следующий проход — через интервал. `stop_requested()` + проверяется перед каждой строкой и между её шагами: по SIGTERM + текущий шаг доводится до commit или отката, новые не начинаются + (спек `graceful-shutdown`, «Остановка уборщика»). """ started = time.monotonic() log = logger.bind(method="clean_stale_pending") @@ -138,23 +140,29 @@ class AttachmentCleanupService: """Убрать одну строку; `False` — её уже нет, она `ready` или её держит другой процесс. + Два шага («Уточнения apply», п. 16 и 21): 1. Пометка — своя транзакция: блокировка, `updated_at` = сейчас, commit. Загрузка, пережившая grace, ждёт блокировку в `mark_ready` и после commit находит строку помеченной: `None`, 503 и компенсация. После пометки строка `ready` уже не станет, - поэтому никакой исход следующих шагов не даёт `ready` без - объекта: ни откат удаления строки, ни DELETE, который S3 + поэтому никакой исход шага 2 не даёт `ready` без объекта: ни + его откат после удачного DELETE в S3, ни DELETE, который S3 выполнил после срока вызова (verify W1). - 2. Объект — вне транзакции, после подтверждённой пометки. Отказ - S3 прерывает проход, помеченная строка ждёт следующего. - 3. Строка — своя транзакция с той же блокировкой; занята или уже - убрана — пропуск, следующий проход доводит. - Повтор после сбоя между шагами идемпотентен: пометка ставится - заново, удаление объекта и строки — те же. `stop_requested()` - проверяется и между шагами: по SIGTERM доводится только текущий - шаг (не дольше срока шага с БД, 6 с), и уборщик укладывается в - срок остановки контейнера (10 с); помеченная строка ждёт - следующего запуска. + 2. Объект и строка — одна транзакция под той же блокировкой: + DELETE объекта, затем DELETE строки, commit. Строки нет или + она занята — пропуск. Блокировка держится и на время DELETE в + S3: прежний `mark_ready` (реплика без проверки пометки), + пришедший во время шага, ждёт commit и находит 0 строк, а + ставший `ready` между шагами — с целым объектом, шаг 2 его + пропускает (verify W1 повторной проверки). Вызов S3 внутри + транзакции — не дольше `[s3] timeout_seconds` (5 с), меньше + `idle_in_transaction_session_timeout` (10 с). Отказ S3 откатывает + шаг 2 и прерывает проход, помеченная строка ждёт следующего. + Повтор после сбоя идемпотентен: пометка ставится заново, удаление + объекта и строки — те же. `stop_requested()` проверяется и между + шагами: по SIGTERM доводится только текущий шаг (не дольше срока + шага с БД, 6 с), и уборщик укладывается в срок остановки + контейнера (10 с); помеченная строка ждёт следующего запуска. """ async with self.db_scope() as db_session: stale = await attachment_repo.lock_stale_pending( @@ -170,12 +178,6 @@ class AttachmentCleanupService: updated_at=utcnow(), ) await db_session.commit() - if stop_requested(): - return False - await attachment_object_repo.delete_original( - self.storage, - key=stale.object_key, - ) if stop_requested(): return False async with self.db_scope() as db_session: @@ -186,6 +188,10 @@ class AttachmentCleanupService: ) if locked is None: return False + await attachment_object_repo.delete_original( + self.storage, + key=locked.object_key, + ) await attachment_repo.delete_attachment( db_session=db_session, attachment_id=locked.id,