fix: delete the object and the row in one locked cleanup transaction

Keep the committed mark, then delete the object and the row under the
same row lock, so an older replica without the mark check that waits on
the row finds it gone instead of promoting it to ready after the object
delete. A mixed-version stand is no worse than before the mark; document
the upgrade order (replicas first, cleaner last) and fix stale wording.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-21 22:08:29 +03:00
co-authored by Claude Opus 5.5
parent 6551839807
commit 5889ca2ad7
13 changed files with 384 additions and 136 deletions
+18 -8
View File
@@ -312,14 +312,24 @@ rolling_update` уборщик работает на прежнем образе
только расширяется (индекс). Новый код уборщика — `docker compose up -d только расширяется (индекс). Новый код уборщика — `docker compose up -d
--no-deps cleaner` или `make run_docker`; его SIGTERM доводит текущий --no-deps cleaner` или `make run_docker`; его SIGTERM доводит текущий
шаг строки и выходит за ≤ 6 с. Пометка строки к уборке (verify W1, шаг строки и выходит за ≤ 6 с. Пометка строки к уборке (verify W1,
design `upload-consistency`, «Уточнения apply», п. 16) защищает от design `upload-consistency`, «Уточнения apply», п. 16 и 21) полностью
`ready` без объекта, только когда новые и реплики, и уборщик: прежний защищает от `ready` без объекта, только когда новые и реплики, и
уборщик строку не помечает, а реплики прежней версии пометку не уборщик. Смеси версий не хуже, чем до правки:
проверяют. До конца замены и `up -d --no-deps cleaner` действует - новый уборщик + реплики до `87c48b9` (пометку не проверяют): объект и
прежний остаточный риск (загрузка, пережившая grace, при откате строка удаляются одной транзакцией под блокировкой, поэтому прежний
транзакции уборщика), это ограничение в `REPORT.md`. Обратная `mark_ready` либо делает строку `ready` с целым объектом (уборщик её
совместимость есть: новый `mark_ready` на строках, вставленных прежним пропускает), либо ждёт commit и находит 0 строк;
кодом, работает (вставка всегда писала `created_at` = `updated_at`). - прежний уборщик (пометку не ставит) + новые реплики — как до правки.
В обеих остаётся прежний риск: загрузка, пережившая 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`, **Bootstrap S3 скрипт не запускает** (design change `s3-storage`,
решение 9): новая реплика поднимается с `--no-deps`. Bootstrap, как решение 9): новая реплика поднимается с `--no-deps`. Bootstrap, как
+4 -1
View File
@@ -169,7 +169,10 @@ paths:
ошибок, без значений полей), «Stopped cleaner before startup» — как у ошибок, без значений полей), «Stopped cleaner before startup» — как у
API. API.
- `attachment_cleanup_service`: `info` «Removed stale attachment» - `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`, «Finished cleanup pass» / «Interrupted cleanup pass» (`removed`,
`skipped`, `interrupted_by`, `duration_ms`): `warning` при отказе S3 `skipped`, `interrupted_by`, `duration_ms`): `warning` при отказе S3
или БД, `info`, если что-то убрано или проход остановлен сигналом, или БД, `info`, если что-то убрано или проход остановлен сигналом,
+5 -1
View File
@@ -64,7 +64,11 @@ paths:
держат), `mark_removing` (пометка к уборке: `updated_at` = время держат), `mark_removing` (пометка к уборке: `updated_at` = время
уборщика, позже `created_at`; без миграции, CHECK уборщика, позже `created_at`; без миграции, CHECK
`updated_after_created` выполняется), `delete_attachment` `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)`), а не параметр: условие (`literal(..., literal_execute=True)`), а не параметр: условие
частичного индекса `ix_attachments_pending_created_at` планировщик частичного индекса `ix_attachments_pending_created_at` планировщик
доказывает только по константе, и общий план подготовленного доказывает только по константе, и общий план подготовленного
+5 -3
View File
@@ -106,9 +106,11 @@ access_log=False)`. Импорты в `src/__main__.py` — внутри `if __n
engine и клиента S3; затем обработчики SIGTERM и SIGINT asyncio, engine и клиента S3; затем обработчики SIGTERM и SIGINT asyncio,
`early_stop.disarm()`, «Started cleaner». `early_stop.disarm()`, «Started cleaner».
- Цикл: проход, затем ожидание `[cleaner] interval_seconds` или - Цикл: проход, затем ожидание `[cleaner] interval_seconds` или
сигнала. SIGTERM / SIGINT ставят флаг: доводится текущий шаг строки — сигнала. SIGTERM / SIGINT ставят флаг: доводится до commit или отката
пометка, удаление объекта или строки (не дольше срока шага с БД, 6 с; текущий шаг строки — пометка или уборка (объект и строка одной
флаг проверяется и между шагами), новые не берутся, клиенты закрываются, транзакцией; не дольше срока шага с БД, 6 с, DELETE в S3 внутри него
≤ 5 с; флаг проверяется и между шагами), новые не берутся, клиенты
закрываются,
«Stopped cleaner» и код 0 — раньше `stop_grace_period` 10 с. Сигнал «Stopped cleaner» и код 0 — раньше `stop_grace_period` 10 с. Сигнал
до обработчиков asyncio — ранний обработчик: «Stopped cleaner before до обработчиков asyncio — ранний обработчик: «Stopped cleaner before
startup», код 0. startup», код 0.
+13 -10
View File
@@ -97,23 +97,26 @@ paths:
(`services/attachment_cleanup.py`), сервис процесса уборщика, а не (`services/attachment_cleanup.py`), сервис процесса уборщика, а не
реплик API: `clean_stale_pending(*, older_than, batch_size, реплик API: `clean_stale_pending(*, older_than, batch_size,
stop_requested)`. Кандидаты — короткая транзакция без блокировки stop_requested)`. Кандидаты — короткая транзакция без блокировки
(keyset), затем каждая строка — три шага (verify W1, design, (keyset), затем каждая строка — два шага (verify W1 и повторный
«Уточнения apply», п. 16): verify, design, «Уточнения apply», п. 16 и 21):
1. транзакция пометки: `lock_stale_pending` (`FOR UPDATE SKIP 1. транзакция пометки: `lock_stale_pending` (`FOR UPDATE SKIP
LOCKED`) → `mark_removing` (`updated_at = utcnow()`) → commit; LOCKED`) → `mark_removing` (`updated_at = utcnow()`) → commit;
2. `delete_original` — вне транзакции, только после подтверждённой 2. транзакция уборки: снова `lock_stale_pending` →
пометки; `delete_original` → `delete_attachment` → commit; строки нет или
3. транзакция строки: снова `lock_stale_pending` → она занята — пропуск.
`delete_attachment` → commit; строки нет или она занята —
пропуск.
Помеченную строку `mark_ready` в `ready` не переводит (`updated_at = Помеченную строку `mark_ready` в `ready` не переводит (`updated_at =
created_at`), поэтому сбой после удаления объекта (откат шага 3, created_at`), поэтому сбой после удаления объекта (откат шага 2,
DELETE, который S3 выполнил после срока) не даёт `ready` без DELETE, который S3 выполнил после срока) не даёт `ready` без
объекта. Не одна транзакция на строку: её откат после удачного объекта. Не одна транзакция на строку: её откат после удачного
DELETE в S3 вернул бы строку непомеченной, и загрузка, пережившая DELETE в S3 вернул бы строку непомеченной, и загрузка, пережившая
grace, сделала бы её `ready` без объекта. Объект раньше строки: сбой grace, сделала бы её `ready` без объекта. DELETE в S3 — под
между ними оставляет строку без объекта, а не наоборот. Отказ S3 или блокировкой шага 2, а не между транзакциями: реплика до `87c48b9`
пометку не проверяет и иначе сделала бы строку `ready` прямо перед
удалением её объекта. Вызов S3 внутри транзакции ≤ `[s3]
timeout_seconds` (5 с) < `idle_in_transaction_session_timeout` (10 с).
Объект раньше строки: сбой между ними оставляет строку без объекта, а
не наоборот. Отказ S3 или
БД прерывает проход (`session_scope` уже записал `warning`), БД прерывает проход (`session_scope` уже записал `warning`),
помеченная строка ждёт следующего прохода — пометка ставится заново. помеченная строка ждёт следующего прохода — пометка ставится заново.
`stop_requested()` проверяется перед строкой и между шагами. Итог — `stop_requested()` проверяется перед строкой и между шагами. Итог —
+6 -2
View File
@@ -128,7 +128,9 @@ paths:
`BEFORE UPDATE OF status`, пока строку не уберёт уборщик: на уровне `BEFORE UPDATE OF status`, пока строку не уберёт уборщик: на уровне
оператора строка не заблокирована, а пометку уборщика (только оператора строка не заблокирована, а пометку уборщика (только
`updated_at`) `OF status` не задерживает; `undeletable` — как `updated_at`) `OF status` не задерживает; `undeletable` — как
`outlive`, и удаление строки падает), `clear-fail-attachments`, `outlive`, и удаление строки падает — в той же транзакции уборки,
где уборщик уже удалил объект: это откат второго шага после удачного
DELETE в S3), `clear-fail-attachments`,
`kill-api` / `start-api` (`docker kill` / `docker start` `kill-api` / `start-api` (`docker kill` / `docker start`
`<FAULT_PROJECT>-api`, ожидание `healthy`); `<FAULT_PROJECT>-api`, ожидание `healthy`);
- тесты: `test_upload_with_object_storage_stopped` (+ «Незавершённая - тесты: `test_upload_with_object_storage_stopped` (+ «Незавершённая
@@ -161,7 +163,9 @@ paths:
сценарии прежний код уже выполнял. Тесты по замечаниям verify: сценарии прежний код уже выполнял. Тесты по замечаниям verify:
`test_cleaner_failure_after_object_delete` красный на коде до пометки `test_cleaner_failure_after_object_delete` красный на коде до пометки
(201: ждавший `mark_ready` перевёл строку в `ready` после отката (201: ждавший `mark_ready` перевёл строку в `ready` после отката
уборщика, объект уже удалён); `test_ready_commit_outcome_unknown` и уборщика, объект уже удалён; на двухшаговой схеме — пометка, затем
объект и строка одной транзакцией — тест не менялся и проверяет тот
же откат); `test_ready_commit_outcome_unknown` и
`test_upload_outlives_grace` на том коде зелёные (ветки были верны) и `test_upload_outlives_grace` на том коде зелёные (ветки были верны) и
красные на временных регрессиях — компенсация на любой сбой (объекта красные на временных регрессиях — компенсация на любой сбой (объекта
нет сразу после 503) и возврат `RuntimeError` (500); нет сразу после 503) и возврат `RuntimeError` (500);
+6 -5
View File
@@ -131,9 +131,10 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore
загрузки убирает только уборщик — отдельный сервис `cleaner` на образе загрузки убирает только уборщик — отдельный сервис `cleaner` на образе
API, а не реплики: строки `pending` старше `[cleaner] API, а не реплики: строки `pending` старше `[cleaner]
pending_grace_seconds` (900 с; больше границы живой загрузки 17 с, pending_grace_seconds` (900 с; больше границы живой загрузки 17 с,
иначе уборщик не стартует) под `FOR UPDATE SKIP LOCKED`: сначала иначе уборщик не стартует) под `FOR UPDATE SKIP LOCKED`, в два шага:
пометка строки (`updated_at`) отдельной транзакцией, затем объект, пометка строки (`updated_at`) отдельной транзакцией, затем объект и
затем строка; помеченную строку `mark_ready` в `ready` не переводит, строка одной транзакцией под блокировкой (объект раньше строки);
помеченную строку `mark_ready` в `ready` не переводит,
`ready` уборщик не трогает. У уборщика свой пользователь S3 — только `ready` уборщик не трогает. У уборщика свой пользователь S3 — только
чтение и удаление объектов своего bucket, ключи `S3_CLEANER_*` только чтение и удаление объектов своего bucket, ключи `S3_CLEANER_*` только
у него и bootstrap (`docker.md`, `settings.md`). у него и bootstrap (`docker.md`, `settings.md`).
@@ -359,7 +360,7 @@ src/
__main__.py # python -m src: early_stop.install() до импорта приложения → main.main() __main__.py # python -m src: early_stop.install() до импорта приложения → main.main()
main.py # FastAPI app: lifespan, middlewares, обработчики ошибок, uvicorn.run 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 # 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 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/ api/
routers/health.py # /health/live, /health/ready: вне версии, без идентификации routers/health.py # /health/live, /health/ready: вне версии, без идентификации
@@ -377,7 +378,7 @@ src/
repos/message.py # MESSAGE_COLUMNS с ARRAY(подзапрос attachment_ids по position), вставка связей одной вставкой repos/message.py # MESSAGE_COLUMNS с ARRAY(подзапрос attachment_ids по position), вставка связей одной вставкой
services/<domain>.py # <Domain>Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем; отправка — ключ, сообщение и связи с вложениями одной транзакцией services/<domain>.py # <Domain>Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем; отправка — ключ, сообщение и связи с вложениями одной транзакцией
services/attachment.py # AttachmentService(db_scope, cache, storage): загрузка (проверки → тело со счётчиком в BytesIO, bytes без копии → структура и SHA-256 в потоке → pending → PUT → ready; сбой ready до COMMIT или пропавшая строка — удаление объекта и 503), метаданные, отдача потоком 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/<domain>.py # доменные исключения, реэкспорт в __init__.py; storage.py — ObjectStorageUnavailable (503) и StoredObjectMissing; attachment.py — 404, 413, 415, 400 обрыва, 500 пропавшего объекта exceptions/<domain>.py # доменные исключения, реэкспорт в __init__.py; storage.py — ObjectStorageUnavailable (503) и StoredObjectMissing; attachment.py — 404, 413, 415, 400 обрыва, 500 пропавшего объекта
infra/ infra/
early_stop.py # ранний обработчик SIGTERM/SIGINT (только stdlib): до старта сервера — запись «Stopped <процесс> before startup» (API, cleaner) и выход 0; disarm() — первая строка lifespan; write_record — запись мимо structlog early_stop.py # ранний обработчик SIGTERM/SIGINT (только stdlib): до старта сервера — запись «Stopped <процесс> before startup» (API, cleaner) и выход 0; disarm() — первая строка lifespan; write_record — запись мимо structlog
+29 -4
View File
@@ -799,7 +799,7 @@ design, «Уточнения apply», пп. 10–15):
`mark_ready` → `None` — 503 вместо 500. `mark_ready` → `None` — 503 вместо 500.
2. **Уборщик — сервис `cleaner`, `python -m src.cleaner`** (решение 2): 2. **Уборщик — сервис `cleaner`, `python -m src.cleaner`** (решение 2):
- свой engine (пул 1) и клиент S3, цикл с интервалом, `--once`; - свой engine (пул 1) и клиент S3, цикл с интервалом, `--once`;
- SIGTERM — довести строку и выйти с кодом 0; - SIGTERM — довести текущий шаг строки и выйти с кодом 0;
- healthcheck образа выключен; - healthcheck образа выключен;
- в консоли (`make run_dev`) уборщика нет. - в консоли (`make run_dev`) уборщика нет.
3. **Проход** (решение 3): строка под `FOR UPDATE SKIP LOCKED` → DELETE 3. **Проход** (решение 3): строка под `FOR UPDATE SKIP LOCKED` → DELETE
@@ -807,7 +807,8 @@ design, «Уточнения apply», пп. 10–15):
`mark_ready` загрузки, пережившей grace. Остаток риска: API заморожен `mark_ready` загрузки, пережившей grace. Остаток риска: API заморожен
дольше grace посреди PUT — объект без строки, его находит сверка дольше grace посреди PUT — объект без строки, его находит сверка
трека 2. После verify — пометка строки отдельной транзакцией до трека 2. После verify — пометка строки отдельной транзакцией до
DELETE объекта (решение 18 ниже). DELETE объекта (решение 18 ниже), после повторного — объект и строка
одной транзакцией под блокировкой (решение 23).
4. **Grace 900 с, интервал 60 с, выборка 100** (решение 4): 4. **Grace 900 с, интервал 60 с, выборка 100** (решение 4):
- граница живой загрузки от строки до `ready`: B = 2 × 6 + 5 = 17 с, - граница живой загрузки от строки до `ready`: B = 2 × 6 + 5 = 17 с,
запас ×50; запас ×50;
@@ -857,7 +858,8 @@ apply»):
общий план asyncpg иначе не взял бы частичный индекс. План — `Index общий план asyncpg иначе не взял бы частичный индекс. План — `Index
Scan` по `ix_attachments_pending_created_at`. Scan` по `ix_attachments_pending_created_at`.
14. **SIGTERM посреди прохода** — `stop_requested` у 14. **SIGTERM посреди прохода** — `stop_requested` у
`clean_stale_pending`: строка доводится, новые не берутся. `clean_stale_pending`: текущий шаг строки доводится до commit или
отката, новые не начинаются (после решения 19).
15. **Неверные настройки уборщика** — запись без значений полей и код 2, 15. **Неверные настройки уборщика** — запись без значений полей и код 2,
а не traceback. а не traceback.
16. **`entrypoint` у сервиса `cleaner`**, чтобы `docker compose run 16. **`entrypoint` у сервиса `cleaner`**, чтобы `docker compose run
@@ -879,7 +881,8 @@ design, «Уточнения apply», п. 16–20; tasks, группа 11):
уборщик) и объект без строки, если зомби дописал объект после уборщик) и объект без строки, если зомби дописал объект после
уборки, а компенсация не удалась. уборки, а компенсация не удалась.
19. **SIGTERM уборщика — между шагами строки**: три шага удлинили бы 19. **SIGTERM уборщика — между шагами строки**: три шага удлинили бы
худшую остановку до 17 с; доводится только текущий шаг (≤ 6 с). худшую остановку до 17 с (после решения 23 шагов два — до 12 с);
доводится только текущий шаг (≤ 6 с).
Требование `graceful-shutdown` «Остановка уборщика» уточнено. Требование `graceful-shutdown` «Остановка уборщика» уточнено.
20. **W2, W3 — режимы hook `commit` и `outlive`** и тесты веток «исход 20. **W2, W3 — режимы hook `commit` и `outlive`** и тесты веток «исход
COMMIT неизвестен» и «строку убрал уборщик до `ready`»; W1 — режим COMMIT неизвестен» и «строку убрал уборщик до `ready`»; W1 — режим
@@ -891,6 +894,28 @@ design, «Уточнения apply», п. 16–20; tasks, группа 11):
22. **W4 и S1** — evidence «Отказ S3 во время прохода» с закоммиченного 22. **W4 и S1** — evidence «Отказ S3 во время прохода» с закоммиченного
кода; `docker.md` — `entrypoint` уборщика. кода; `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` и 1. Как перенести секреты уборщика `S3_CLEANER_ACCESS_KEY` и
+45 -23
View File
@@ -319,20 +319,20 @@ PostgreSQL **до** записи — строка `pending` с `object_key` фи
выбирает строки `pending` старше `[cleaner] pending_grace_seconds` выбирает строки `pending` старше `[cleaner] pending_grace_seconds`
(900 с) выборками по 100 (keyset по `(created_at, id)`, частичный индекс (900 с) выборками по 100 (keyset по `(created_at, id)`, частичный индекс
`ix_attachments_pending_created_at` — план в `ix_attachments_pending_created_at` — план в
`evidence/migrations/pending-index.md`) и каждую убирает в три шага `evidence/migrations/pending-index.md`) и каждую убирает в два шага
(после verify, `87c48b9`): (после двух verify):
1. транзакция пометки: `SELECT … FOR UPDATE SKIP LOCKED` той же строки 1. транзакция пометки: `SELECT … FOR UPDATE SKIP LOCKED` той же строки
(всё ещё `pending` и старше порога; нет — пропуск), `updated_at = (всё ещё `pending` и старше порога; нет — пропуск), `updated_at =
now()` уборщика, commit; now()` уборщика, commit;
2. DELETE объекта ключом уборщика, вне транзакции (отсутствие объекта — 2. транзакция уборки: та же блокировка (нет строки или занята —
тоже 204); пропуск), DELETE объекта ключом уборщика (отсутствие объекта — тоже
3. транзакция строки: та же блокировка, DELETE строки, commit. 204), DELETE строки, commit.
Объект удаляется раньше строки: сбой между шагами оставляет строку без Объект удаляется раньше строки: сбой между ними оставляет строку без
объекта (следующий проход её доуберёт, пометка ставится заново), а не объекта (следующий проход её доуберёт, пометка ставится заново), а не
объект без строки. Строки `ready` выборка не видит никогда. SIGTERM объект без строки. Строки `ready` выборка не видит никогда. SIGTERM
доводит только текущий шаг (≤ 6 с), между шагами уборщик останавливается доводит только текущий шаг до commit или отката (≤ 6 с), между шагами
сам. уборщик останавливается сам.
**Зачем блокировка.** Загрузка короче grace, но процесс API, замороженный **Зачем блокировка.** Загрузка короче grace, но процесс API, замороженный
дольше grace (`docker pause`, пауза ВМ), после разморозки дойдёт до дольше grace (`docker pause`, пауза ВМ), после разморозки дойдёт до
@@ -352,9 +352,20 @@ DELETE, который S3 выполнил после срока вызова,
пометка зафиксирована до DELETE объекта. Помеченная строка `ready` уже не пометка зафиксирована до DELETE объекта. Помеченная строка `ready` уже не
станет: загрузка получает 503 и удаляет свой объект, уборку доводит станет: загрузка получает 503 и удаляет свой объект, уборку доводит
следующий проход (`test_cleaner_failure_after_object_delete`). Миграции следующий проход (`test_cleaner_failure_after_object_delete`). Миграции
нет, CHECK `updated_at >= created_at` выполняется. Блокировку держат нет, CHECK `updated_at >= created_at` выполняется.
только две короткие транзакции; DELETE в S3 — между ними, в своём пуле
уборщика из одного соединения. **Зачем 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 — от **Grace period и его обоснование.** Граница живой загрузки B — от
записи `created_at` строки до фиксации `ready`: tx1 ≤ записи `created_at` строки до фиксации `ready`: tx1 ≤
@@ -381,13 +392,14 @@ DELETE, который S3 выполнил после срока вызова,
основание удалять) и оставлено для глубокой сверки трека 2. основание удалять) и оставлено для глубокой сверки трека 2.
**Отказы хранилищ в уборщике.** S3 недоступен, не ответил, отказал в **Отказы хранилищ в уборщике.** S3 недоступен, не ответил, отказал в
доступе или bucket нет — транзакция строки откатывается, проход доступе или bucket нет — транзакция уборки откатывается, строка остаётся
прерывается на первой строке (`warning`), следующий — через интервал. `pending` и помеченной, проход прерывается на первой строке (`warning`),
следующий — через интервал (пометка ставится заново).
PostgreSQL недоступен — проход пропускается (`warning`). Непредвиденная PostgreSQL недоступен — проход пропускается (`warning`). Непредвиденная
ошибка — `error` с traceback, процесс живёт. Перезапуск не нужен: у ошибка — `error` с traceback, процесс живёт. Перезапуск не нужен: у
клиента S3 нет повторов, пул PostgreSQL — с `pool_pre_ping` клиента S3 нет повторов, пул PostgreSQL — с `pool_pre_ping`
(`test_cleaner_survives_outages`). SIGTERM: текущая строка доводится, (`test_cleaner_survives_outages`). SIGTERM: текущий шаг уборки доводится
выход с кодом 0 за ~0,6 с. до commit или отката, новые не начинаются, выход с кодом 0 за ~0,6 с.
**Доказательства**: `evidence/attachments/consistency.md` (рабочий **Доказательства**: `evidence/attachments/consistency.md` (рабочий
стенд: S3 заморожен и сбой фиксации `ready` → 503, строки не видны, стенд: S3 заморожен и сбой фиксации `ready` → 503, строки не видны,
@@ -605,14 +617,24 @@ S3 (change `s3-storage`):
сверка bucket и БД (трек 2). `ready` без объекта при этом не возникает: сверка bucket и БД (трек 2). `ready` без объекта при этом не возникает:
уборщик помечает строку до удаления объекта, а помеченную `mark_ready` уборщик помечает строку до удаления объекта, а помеченную `mark_ready`
в `ready` не переводит. в `ready` не переводит.
- **Окно `make rolling_update` для пометки.** Реплики прежней версии - **Смесь версий уборщика и реплик.** Реплики до `87c48b9` (`f2dc0b3`
(`f2dc0b3` и раньше) пометку не проверяют, а скрипт замены уборщика не и раньше) пометку не проверяют, а прежний уборщик её не ставит;
пересоздаёт (прежний не помечает). Пока замена не закончена и не `make rolling_update` уборщика не пересоздаёт. Обе смеси не хуже, чем
выполнен `docker compose up -d --no-deps cleaner`, для загрузки, до правки:
пережившей grace, остаётся прежний риск: откат транзакции уборщика - новый уборщик + прежние реплики: объект и строка удаляются одной
после удачного DELETE в S3 даёт `ready` без объекта. Нужно совпадение транзакцией под блокировкой, прежний `mark_ready` либо делает строку
зомби дольше 15 мин и сбоя в окне меньше секунды. Смешанные версии `ready` с целым объектом (уборщик её пропускает), либо ждёт commit и
друг другу не мешают: новый `mark_ready` работает на строках прежних находит 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`). реплик (вставка всегда писала `created_at` = `updated_at`).
- **Проверка grace — по настройкам уборщика.** `config.toml` у API и - **Проверка grace — по настройкам уборщика.** `config.toml` у API и
уборщика общий, но подмена сроков окружением только у API уборщика общий, но подмена сроков окружением только у API
+164 -51
View File
@@ -171,8 +171,10 @@ COMMIT. Отвергнута: вложение могло стать `ready`, и
- `src/infra/early_stop.py` получает имя процесса для записи «Stopped - `src/infra/early_stop.py` получает имя процесса для записи «Stopped
… before startup»; у API текст прежний; … before startup»; у API текст прежний;
- после старта цикла — обработчики asyncio. SIGTERM и SIGINT ставят - после старта цикла — обработчики asyncio. SIGTERM и SIGINT ставят
флаг, текущая строка доводится (не дольше срока шага с БД, 6 с), и флаг, текущий шаг уборки строки доводится до commit или отката (не
процесс выходит с кодом 0 и записью «Stopped cleaner»; дольше срока шага с БД, 6 с), новые шаги не начинаются, и процесс
выходит с кодом 0 и записью «Stopped cleaner» («Уточнения apply»,
п. 16 и 21);
- `stop_grace_period` 10 с, как у `api`. - `stop_grace_period` 10 с, как у `api`.
- Healthcheck образа (HTTP) в сервисе выключен (`healthcheck: disable: - Healthcheck образа (HTTP) в сервисе выключен (`healthcheck: disable:
true`). Живость видна по журналу: старт, проходы, отказы. Уборщик ни true`). Живость видна по журналу: старт, проходы, отказы. Уборщик ни
@@ -204,20 +206,21 @@ cron-контейнер. Отвергнуты: ещё один образ, S3 и
(created_at, id) > (:after) ORDER BY created_at, id LIMIT (created_at, id) > (:after) ORDER BY created_at, id LIMIT
:batch_size`. Это keyset, как у истории, по частичному индексу :batch_size`. Это keyset, как у истории, по частичному индексу
(решение 6). Занятая строка не возвращает проход к началу. (решение 6). Занятая строка не возвращает проход к началу.
3. Каждый кандидат — три шага (после verify W1, «Уточнения apply», 3. Каждый кандидат — два шага (после verify W1 и повторного verify,
п. 16; было — одна транзакция с DELETE объекта внутри): «Уточнения apply», п. 16 и 21; было — одна транзакция с DELETE
объекта внутри, без пометки):
1. транзакция пометки: `SELECT … WHERE id = :id AND status = 1. транзакция пометки: `SELECT … WHERE id = :id AND status =
'pending' AND created_at < :older_than FOR UPDATE SKIP LOCKED` 'pending' AND created_at < :older_than FOR UPDATE SKIP LOCKED`
(нет строки — её уже убрали, она стала `ready` или её держит (нет строки — её уже убрали, она стала `ready` или её держит
другой процесс: пропуск) → `UPDATE … SET updated_at = utcnow()` → другой процесс: пропуск) → `UPDATE … SET updated_at = utcnow()` →
commit; commit;
2. `storage.delete(object_key)` вне транзакции: 204 и для 2. транзакция уборки: та же блокировка (нет строки или занята —
отсутствующего объекта; пропуск) → `storage.delete(object_key)` (204 и для отсутствующего
3. транзакция строки: та же блокировка → `DELETE FROM attachments объекта) → `DELETE FROM attachments WHERE id = :id` → commit.
WHERE id = :id` → commit.
Отказ S3 прерывает проход: помеченная строка остаётся `pending`, Отказ S3 прерывает проход: шаг 2 откатывается, помеченная строка
следующий проход ставит пометку заново (решение 5). остаётся `pending`, следующий проход ставит пометку заново (решение
5).
4. Итог — DTO: сколько убрано, сколько пропущено, причина прерывания, 4. Итог — DTO: сколько убрано, сколько пропущено, причина прерывания,
длительность. длительность.
@@ -250,14 +253,26 @@ grace, после разморозки дойдёт до `mark_ready`. Без б
`updated_at = created_at`. Вставка пишет оба поля одним значением `updated_at = created_at`. Вставка пишет оба поля одним значением
(`now`), а пометка — время уборщика, оно позже порога прохода и тем (`now`), а пометка — время уборщика, оно позже порога прохода и тем
более `created_at`. Помеченная строка `ready` уже не станет, и любой более `created_at`. Помеченная строка `ready` уже не станет, и любой
исход шагов 2–3 оставляет её `pending`: загрузка получает `None` (503 и исход шага 2 оставляет её `pending`: загрузка получает `None` (503 и
компенсация), уборку доводит следующий проход. Миграции нет, CHECK компенсация), уборку доводит следующий проход. Миграции нет, CHECK
`updated_after_created` выполняется. `updated_after_created` выполняется.
Блокировку и соединение уборщика держат только короткие транзакции Зачем DELETE в S3 под блокировкой шага 2, а не между транзакциями
пометки и удаления строки; DELETE в S3 — между ними, вне транзакции. (повторный verify W1). Прежний `mark_ready` (реплики до `87c48b9`)
Пул у уборщика свой, на реплики это не влияет. Сроки шага: `[s3] пометку не проверяет. Если бы объект удалялся после commit пометки без
timeout_seconds` (5) и `[database] request_timeout_seconds` (6) < блокировки, такая реплика могла бы сделать строку `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 с). `idle_in_transaction_session_timeout` (10 с).
Остаток риска, назван в спеке и `REPORT.md`. Процесс API заморожен Остаток риска, назван в спеке и `REPORT.md`. Процесс API заморожен
@@ -265,9 +280,9 @@ timeout_seconds` (5) и `[database] request_timeout_seconds` (6) <
S3 принял тело. Компенсации при этом нет: PUT для API завершился S3 принял тело. Компенсации при этом нет: PUT для API завершился
ошибкой по сроку. Или PUT прошёл, `mark_ready` получил `None`, а ошибкой по сроку. Или PUT прошёл, `mark_ready` получил `None`, а
удаление при компенсации не удалось. Объект остаётся без строки, его удаление при компенсации не удалось. Объект остаётся без строки, его
находит только сверка списком bucket (трек 2). Второй остаток — окно находит только сверка списком bucket (трек 2). Второй остаток — смесь
`make rolling_update` (п. 16): реплики прежней версии пометку не версий (п. 16 и 21): реплики до `87c48b9` пометку не проверяют, и для их
проверяют. загрузок остаётся риск до правки — откат шага 2 после удачного DELETE.
*Альтернатива:* без блокировки, условие возраста в `mark_ready` (`AND *Альтернатива:* без блокировки, условие возраста в `mark_ready` (`AND
created_at > :deadline`). Отвергнута: API пришлось бы знать grace created_at > :deadline`). Отвергнута: API пришлось бы знать grace
@@ -326,9 +341,10 @@ B = 2 × 6 + 5 = 17 с. Тело и проверка изображения ид
### 5. Отказы хранилищ в уборщике ### 5. Отказы хранилищ в уборщике
- S3 недоступен, не ответил, отказал в доступе или bucket нет - S3 недоступен, не ответил, отказал в доступе или bucket нет
(`ObjectStorageUnavailable`): транзакция строки откатывается, проход (`ObjectStorageUnavailable`): транзакция уборки (шаг 2 решения 3)
откатывается, строка остаётся `pending` и помеченной, проход
прерывается на первой строке, в журнале `warning` с причиной. Дальше прерывается на первой строке, в журнале `warning` с причиной. Дальше
— через интервал. Удалённый bucket SeaweedFS отдаёт `NoSuchBucket` — через интервал, пометка ставится заново. Удалённый bucket SeaweedFS отдаёт `NoSuchBucket`
(проба), клиент переводит его в 503, строки остаются. Запись (проба), клиент переводит его в 503, строки остаются. Запись
`KNOWN_ISSUES.md` о bootstrap после удаления bucket — трек 2. `KNOWN_ISSUES.md` о bootstrap после удаления bucket — трек 2.
- PostgreSQL недоступен (`ServiceUnavailable` общего контекста сессии, - PostgreSQL недоступен (`ServiceUnavailable` общего контекста сессии,
@@ -589,24 +605,32 @@ Evidence (с закоммиченного кода):
названо прямо. названо прямо.
- [`ready` без объекта при откате транзакции уборщика после удачного - [`ready` без объекта при откате транзакции уборщика после удачного
DELETE в S3 (verify W1)] → закрыто пометкой строки отдельной DELETE в S3 (verify W1)] → закрыто пометкой строки отдельной
транзакцией до DELETE объекта (решение 3, «Уточнения apply», п. 16). транзакцией до DELETE объекта (решение 3, «Уточнения apply», п. 16 и
Остаток — окно `make rolling_update`: реплики прежней версии 21) на стенде одной версии. Смесь версий не хуже, чем до правки:
пометку не проверяют, прежний уборщик её не ставит. Оно длится до новый уборщик с репликами до `87c48b9` (пометку не проверяют) и
конца замены и `docker compose up -d --no-deps cleaner`, нужен ещё и прежний уборщик с новыми репликами (пометку не ставит) оставляют
зомби дольше grace — ограничение в `REPORT.md`. только прежний риск — откат транзакции уборки после удачного DELETE,
- [Три шага на строку вместо одной транзакции: SIGTERM посреди строки для загрузки-зомби дольше grace. Порядок обновления это окно
мог бы ждать 6 + 5 + 6 с при зависших хранилищах] → флаг остановки сокращает: вперёд — сначала реплики (`make rolling_update`), потом
проверяется и между шагами, доводится только текущий шаг (≤ 6 с < `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` уточнено. 10 с `stop_grace_period`). Требование `graceful-shutdown` уточнено.
- [Компенсация добавляет до 5 с к ответу 503, если S3 стал медленным - [Компенсация добавляет до 5 с к ответу 503, если S3 стал медленным
после удачного PUT] → только ветка сбоя tx2. Худший путь загрузки и после удачного PUT] → только ветка сбоя tx2. Худший путь загрузки и
так длиннее `timeout server` HAProxy (`attachments`, Risks). Пересмотр так длиннее `timeout server` HAProxy (`attachments`, Risks). Пересмотр
цепочки — `upload-memory`. цепочки — `upload-memory`.
- [Транзакции уборщика держат блокировку строки] → только короткие - [Транзакции уборщика держат блокировку строки, транзакция уборки — и
транзакции пометки и удаления строки и только строки старше grace; на время DELETE в S3] → только строки старше grace; транзакция
DELETE в S3 — между ними, вне транзакции (после verify W1). пометки короткая, транзакция уборки — не дольше срока шага (6 с, DELETE
`mark_ready` зомби-загрузки подождёт — это и нужно. Пул уборщика свой в S3 ≤ 5 с) < `idle_in_transaction_session_timeout` (10 с).
(1 соединение). `mark_ready` зомби-загрузки подождёт — это и нужно: так и прежняя
реплика не делает `ready` строку, объект которой удаляется. Пул
уборщика свой (1 соединение).
- [Долгий отказ S3 копит строки `pending`: каждая попытка загрузки — одна - [Долгий отказ S3 копит строки `pending`: каждая попытка загрузки — одна
строка] → после возврата S3 уборщик убирает их выборками по 100 через строка] → после возврата S3 уборщик убирает их выборками по 100 через
индекс. Стоимость обхода — трек 2. индекс. Стоимость обхода — трек 2.
@@ -623,7 +647,9 @@ Evidence (с закоммиченного кода):
`REPORT.md`. `REPORT.md`.
- [После `make rolling_update` уборщик на прежнем образе] → схема - [После `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` поймает шум, его решении 10. Если `test_pool_keeps_connections` поймает шум, его
калибровка это назовёт. Тогда в apply — пауза уборщика hook-ом на окно калибровка это назовёт. Тогда в apply — пауза уборщика hook-ом на окно
@@ -654,9 +680,11 @@ Evidence (с закоммиченного кода):
s3-bootstrap cleaner`. Bootstrap только добавляет пользователя и права у s3-bootstrap cleaner`. Bootstrap только добавляет пользователя и права у
API не забирает (`balancer.md`). API не забирает (`balancer.md`).
Откат — `make rolling_update COMMIT=d9d44c5 MIGRATE=0` и `docker compose Откат — сначала `docker compose stop cleaner`, затем `make
stop cleaner`. Индекс и пользователь `cleaner` остаются, прежнему коду rolling_update COMMIT=d9d44c5 MIGRATE=0` (уборщик раньше реплик:
они не мешают. Строки `pending` снова копятся до возврата вперёд. «Уточнения apply», п. 21). Индекс и пользователь `cleaner` остаются,
прежнему коду они не мешают. Строки `pending` снова копятся до возврата
вперёд.
## Open Questions ## Open Questions
@@ -707,8 +735,9 @@ stop cleaner`. Индекс и пользователь `cleaner` остаютс
NOT EXISTS …` между `COMMIT` прежних ревизий и `BEGIN` записи версии. NOT EXISTS …` между `COMMIT` прежних ревизий и `BEGIN` записи версии.
4. **Остановка посреди прохода.** У `clean_stale_pending` параметр 4. **Остановка посреди прохода.** У `clean_stale_pending` параметр
`stop_requested` (по умолчанию «никогда»): проверяется перед каждой `stop_requested` (по умолчанию «никогда»): проверяется перед каждой
строкой, и по SIGTERM проход доводит текущую строку и не берёт новые строкой и между шагами строки (п. 16 и 21), и по SIGTERM проход
(спек `graceful-shutdown`, «Остановка уборщика»). Причина в итоге — доводит текущий шаг до commit или отката и новых не начинает (спек
`graceful-shutdown`, «Остановка уборщика»). Причина в итоге —
`interrupted_by="stop"`, запись прохода `info`, `--once` — код 0. `interrupted_by="stop"`, запись прохода `info`, `--once` — код 0.
Флаг цикла один проверял бы только между проходами, а проход из Флаг цикла один проверял бы только между проходами, а проход из
многих выборок длиннее 10 с. многих выборок длиннее 10 с.
@@ -787,9 +816,12 @@ stop cleaner`. Индекс и пользователь `cleaner` остаютс
основной сессии, tasks, группа 11): основной сессии, tasks, группа 11):
16. **W1 закрыт кодом: пометка строки до удаления объекта** (решение 3, 16. **W1 закрыт кодом: пометка строки до удаления объекта** (решение 3,
Risks). Уборщик: `lock_stale_pending` → `mark_removing` (`updated_at Risks). Уборщик (в редакции п. 21 — два шага): `lock_stale_pending`
= utcnow()`) → commit; `delete_original`; `lock_stale_pending` → → `mark_removing` (`updated_at = utcnow()`) → commit;
`delete_attachment` → commit. `mark_ready` — `AND updated_at = `lock_stale_pending` → `delete_original` → `delete_attachment` →
commit. В первой редакции `delete_original` шёл между транзакциями,
вне блокировки — повторный verify нашёл в этом W1 смеси версий
(п. 21). `mark_ready` — `AND updated_at =
created_at`, помеченная строка — `None`, то есть прежняя ветка created_at`, помеченная строка — `None`, то есть прежняя ветка
«строку убрал уборщик» (503 и компенсация). Проверено: «строку убрал уборщик» (503 и компенсация). Проверено:
- вставка `pending` пишет оба поля одним `now` — и в текущем коде, и - вставка `pending` пишет оба поля одним `now` — и в текущем коде, и
@@ -799,16 +831,17 @@ stop cleaner`. Индекс и пользователь `cleaner` остаютс
older_than`, а `utcnow()` уборщика позже `older_than`; older_than`, а `utcnow()` уборщика позже `older_than`;
- повтор после сбоя между транзакциями идемпотентен — пометка - повтор после сбоя между транзакциями идемпотентен — пометка
ставится заново, следующий проход доводит строку; ставится заново, следующий проход доводит строку;
- окно `make rolling_update`: реплики прежней версии (`f2dc0b3`) - смесь версий во время `make rolling_update` и до пересоздания
условия не знают, а скрипт уборщика не пересоздаёт (прежний уборщика: реплики до `87c48b9` (`f2dc0b3` и раньше) условия
уборщик не помечает). До конца замены и `docker compose up -d пометки не знают, а скрипт уборщика не пересоздаёт (прежний
--no-deps cleaner` остаётся прежний риск W1, это ограничение уборщик не помечает). Обе смеси не хуже, чем до правки: остаётся
(`balancer.md`, `REPORT.md`). Смешанные версии друг другу не только прежний риск W1 — откат транзакции уборки после удачного
мешают: прежний уборщик с новыми репликами — поведение до правки, DELETE, для загрузки-зомби дольше grace. Это ограничение
новый уборщик с прежними репликами — тоже. (`balancer.md`, `REPORT.md`); разбор смесей и порядок обновления —
п. 21.
Три шага вместо одной транзакции удлиняют худший SIGTERM посреди Два шага вместо одной транзакции удлиняют худший SIGTERM посреди
строки до 6 + 5 + 6 с при зависших хранилищах. Поэтому строки до 6 + 6 с при зависших хранилищах. Поэтому
`stop_requested()` проверяется и между шагами (доводится только `stop_requested()` проверяется и между шагами (доводится только
текущий, ≤ 6 с < 10 с), а требование `graceful-shutdown` «Остановка текущий, ≤ 6 с < 10 с), а требование `graceful-shutdown` «Остановка
уборщика» уточнено: «довести текущий шаг уборки … новых шагов не уборщика» уточнено: «довести текущий шаг уборки … новых шагов не
@@ -857,3 +890,83 @@ stop cleaner`. Индекс и пользователь `cleaner` остаютс
этом коде PASS, его шаги правка не меняет. этом коде PASS, его шаги правка не меняет.
20. **S1** — `docker.md`, раздел «Уборщик»: `entrypoint`, как в 20. **S1** — `docker.md`, раздел «Уборщик»: `entrypoint`, как в
`docker-compose.yml`, и почему не `command` (п. 6). `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 удалены.
@@ -401,3 +401,57 @@ Verify 2026-10-21: 0 CRITICAL, 4 WARNING, 1 SUGGESTION; решения
`evidence/tests/failure-checks.md` и чисел в `evidence/tests/` и `evidence/tests/failure-checks.md` и чисел в `evidence/tests/` и
`REPORT.md`; `REPORT.md` — порядок уборки с пометкой и остаточный `REPORT.md`; `REPORT.md` — порядок уборки с пометкой и остаточный
риск, новые проверки, строка W4; строка этапа 3 `PLAN.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 <LB>
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`.
+2 -1
View File
@@ -91,7 +91,8 @@ async def run(*, once: bool) -> int:
loop = asyncio.get_running_loop() loop = asyncio.get_running_loop()
for signum in (signal.SIGTERM, signal.SIGINT): for signum in (signal.SIGTERM, signal.SIGINT):
loop.add_signal_handler(signum, stop.set) loop.add_signal_handler(signum, stop.set)
# дальше сигналы обрабатывает цикл: текущая строка доводится # дальше сигналы обрабатывает цикл: текущий шаг уборки доводится до
# commit или отката, новые не начинаются
early_stop.disarm() early_stop.disarm()
engine = create_engine(settings.database) engine = create_engine(settings.database)
+33 -27
View File
@@ -2,11 +2,12 @@
решения 3 и 5). решения 3 и 5).
Сервис процесса уборщика (`src/cleaner/`), а не реплик API. Строка Сервис процесса уборщика (`src/cleaner/`), а не реплик API. Строка
`pending` старше grace: блокировка `FOR UPDATE SKIP LOCKED` → пометка `pending` старше grace, два шага: блокировка `FOR UPDATE SKIP LOCKED` →
(`updated_at`) → commit → удаление объекта → блокировка → удаление пометка (`updated_at`) → commit; та же блокировка → удаление объекта →
строки → commit. Метаданные удаляются последними: объекта без строки удаление строки → commit. Метаданные удаляются последними: объекта без
уборка не оставляет. Строки `ready` выборка не видит, а помеченную строки уборка не оставляет. Строки `ready` выборка не видит, а
строку `mark_ready` в `ready` не переводит («Уточнения apply», п. 16). помеченную строку `mark_ready` в `ready` не переводит («Уточнения
apply», п. 16 и 21).
""" """
import time import time
@@ -59,10 +60,11 @@ class AttachmentCleanupService:
Кандидаты — выборками по `batch_size` (keyset по `(created_at, Кандидаты — выборками по `batch_size` (keyset по `(created_at,
id)`, без блокировки), затем каждая строка отдельно. Отказ S3 id)`, без блокировки), затем каждая строка отдельно. Отказ S3
прерывает проход на первой же строке, отказ PostgreSQL — тоже: в прерывает проход на первой же строке, отказ PostgreSQL — тоже: в
обоих случаях строка остаётся, следующий проход — через интервал. обоих случаях строка остаётся (после пометки — помеченной),
`stop_requested()` проверяется перед каждой строкой: по SIGTERM следующий проход — через интервал. `stop_requested()`
текущая строка доводится, новые не берутся (спек проверяется перед каждой строкой и между её шагами: по SIGTERM
`graceful-shutdown`, «Остановка уборщика»). текущий шаг доводится до commit или отката, новые не начинаются
(спек `graceful-shutdown`, «Остановка уборщика»).
""" """
started = time.monotonic() started = time.monotonic()
log = logger.bind(method="clean_stale_pending") log = logger.bind(method="clean_stale_pending")
@@ -138,23 +140,29 @@ class AttachmentCleanupService:
"""Убрать одну строку; `False` — её уже нет, она `ready` или её """Убрать одну строку; `False` — её уже нет, она `ready` или её
держит другой процесс. держит другой процесс.
Два шага («Уточнения apply», п. 16 и 21):
1. Пометка — своя транзакция: блокировка, `updated_at` = сейчас, 1. Пометка — своя транзакция: блокировка, `updated_at` = сейчас,
commit. Загрузка, пережившая grace, ждёт блокировку в commit. Загрузка, пережившая grace, ждёт блокировку в
`mark_ready` и после commit находит строку помеченной: `None`, `mark_ready` и после commit находит строку помеченной: `None`,
503 и компенсация. После пометки строка `ready` уже не станет, 503 и компенсация. После пометки строка `ready` уже не станет,
поэтому никакой исход следующих шагов не даёт `ready` без поэтому никакой исход шага 2 не даёт `ready` без объекта: ни
объекта: ни откат удаления строки, ни DELETE, который S3 его откат после удачного DELETE в S3, ни DELETE, который S3
выполнил после срока вызова (verify W1). выполнил после срока вызова (verify W1).
2. Объект — вне транзакции, после подтверждённой пометки. Отказ 2. Объект и строка — одна транзакция под той же блокировкой:
S3 прерывает проход, помеченная строка ждёт следующего. DELETE объекта, затем DELETE строки, commit. Строки нет или
3. Строка — своя транзакция с той же блокировкой; занята или уже она занята — пропуск. Блокировка держится и на время DELETE в
убрана — пропуск, следующий проход доводит. S3: прежний `mark_ready` (реплика без проверки пометки),
Повтор после сбоя между шагами идемпотентен: пометка ставится пришедший во время шага, ждёт commit и находит 0 строк, а
заново, удаление объекта и строки — те же. `stop_requested()` ставший `ready` между шагами — с целым объектом, шаг 2 его
проверяется и между шагами: по SIGTERM доводится только текущий пропускает (verify W1 повторной проверки). Вызов S3 внутри
шаг (не дольше срока шага с БД, 6 с), и уборщик укладывается в транзакции — не дольше `[s3] timeout_seconds` (5 с), меньше
срок остановки контейнера (10 с); помеченная строка ждёт `idle_in_transaction_session_timeout` (10 с). Отказ S3 откатывает
следующего запуска. шаг 2 и прерывает проход, помеченная строка ждёт следующего.
Повтор после сбоя идемпотентен: пометка ставится заново, удаление
объекта и строки — те же. `stop_requested()` проверяется и между
шагами: по SIGTERM доводится только текущий шаг (не дольше срока
шага с БД, 6 с), и уборщик укладывается в срок остановки
контейнера (10 с); помеченная строка ждёт следующего запуска.
""" """
async with self.db_scope() as db_session: async with self.db_scope() as db_session:
stale = await attachment_repo.lock_stale_pending( stale = await attachment_repo.lock_stale_pending(
@@ -170,12 +178,6 @@ class AttachmentCleanupService:
updated_at=utcnow(), updated_at=utcnow(),
) )
await db_session.commit() await db_session.commit()
if stop_requested():
return False
await attachment_object_repo.delete_original(
self.storage,
key=stale.object_key,
)
if stop_requested(): if stop_requested():
return False return False
async with self.db_scope() as db_session: async with self.db_scope() as db_session:
@@ -186,6 +188,10 @@ class AttachmentCleanupService:
) )
if locked is None: if locked is None:
return False return False
await attachment_object_repo.delete_original(
self.storage,
key=locked.object_key,
)
await attachment_repo.delete_attachment( await attachment_repo.delete_attachment(
db_session=db_session, db_session=db_session,
attachment_id=locked.id, attachment_id=locked.id,