fix: address upload-consistency verify findings

Mark a stale pending row in its own committed transaction before the
cleaner deletes the object, and let mark_ready promote only unmarked
rows, so a cleaner rollback after the object delete can no longer leave
a ready attachment without its object. Add fault checks for an unknown
COMMIT outcome, an upload outliving the grace period and a cleaner
failure after the object delete; fix the cleaner entrypoint in rules.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-21 21:27:47 +03:00
co-authored by Claude Opus 5.5
parent f2dc0b368a
commit 87c48b940b
20 changed files with 714 additions and 118 deletions
+10 -2
View File
@@ -310,8 +310,16 @@ rolling_update COMMIT=<прежний> MIGRATE=0`.
решение 9): как bootstrap, он не реплика за LB. После `make
rolling_update` уборщик работает на прежнем образе — корректно, схема
только расширяется (индекс). Новый код уборщика — `docker compose up -d
--no-deps cleaner` или `make run_docker`; его SIGTERM доводит текущую
строку и выходит за ≤ 6 с.
--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`).
**Bootstrap S3 скрипт не запускает** (design change `s3-storage`,
решение 9): новая реплика поднимается с `--no-deps`. Bootstrap, как
+6 -2
View File
@@ -272,8 +272,12 @@ git ls-files -z -co --exclude-standard | tar --null -T - -cf - | docker build -t
--exit-code-from s3-bootstrap s3-bootstrap` (`make start_s3`).
- **Уборщик** (с лабы 4, сервис `cleaner`, design change
`upload-consistency`, решения 2 и 9): образ API (`image:
mtusi-messenger:lab4`, `pull_policy: never`), `command: ["python",
"-m", "src.cleaner"]`, `restart: unless-stopped`, без портов.
mtusi-messenger:lab4`, `pull_policy: never`), `entrypoint: ["python",
"-m", "src.cleaner"]`, а не `command`: аргументы после имени сервиса
(`docker compose run --rm --no-deps cleaner --once`) — флаги
уборщика, а с `command` они заменили бы саму команду («executable file
not found», design change `upload-consistency`, «Уточнения apply»,
п. 6). `restart: unless-stopped`, без портов.
Окружение — `<<: [*db-env, *s3-env]`, `DATABASE__POOL_SIZE: "1"` и
ключи уборщика `S3_CLEANER_*` в `S3__ACCESS_KEY_ID` /
`S3__SECRET_ACCESS_KEY`: ни пароля Valkey, ни ключей API, ни
+8 -4
View File
@@ -50,8 +50,10 @@ paths:
Порог `expired_before`, решение «повтор или 409» и commit — в
сервисе. Ключ в исключения и логи не попадает.
- Repo вложений (лаба 4, design change `attachments`, решения 3, 4, 8):
- `attachment.py`: `insert_attachment`, `mark_ready` (`UPDATE … WHERE
status = 'pending' RETURNING`, `None` — строки `pending` нет),
- `attachment.py`: `insert_attachment` (`created_at` и `updated_at`
одним значением), `mark_ready` (`UPDATE … WHERE status = 'pending'
AND updated_at = created_at RETURNING`, `None` — строки `pending` нет
или уборщик пометил её к уборке),
`get_attachment`, `get_attachments` (до 10 строк по первичному
ключу). Значения `content_type` и `status` — `.value` enum на
записи и enum в DTO на чтении. Для уборщика (design change
@@ -59,8 +61,10 @@ paths:
`(created_at, id)`, `status = 'pending'`, `created_at <
older_than`, `LIMIT`), `lock_stale_pending` (те же условия по `id`,
`FOR UPDATE SKIP LOCKED`; `None` — строки нет, она `ready` или её
держат), `delete_attachment` (`RETURNING id`, `bool`); DTO —
`AttachmentInListDTO`. Статус в этих выражениях — константа
держат), `mark_removing` (пометка к уборке: `updated_at` = время
уборщика, позже `created_at`; без миграции, CHECK
`updated_after_created` выполняется), `delete_attachment`
(`RETURNING id`, `bool`); DTO — `AttachmentInListDTO`. Статус в этих выражениях — константа
(`literal(..., literal_execute=True)`), а не параметр: условие
частичного индекса `ix_attachments_pending_created_at` планировщик
доказывает только по константе, и общий план подготовленного
+3 -2
View File
@@ -106,8 +106,9 @@ 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 ставят флаг: доводится текущий шаг строки —
пометка, удаление объекта или строки (не дольше срока шага с БД, 6 с;
флаг проверяется и между шагами), новые не берутся, клиенты закрываются,
«Stopped cleaner» и код 0 — раньше `stop_grace_period` 10 с. Сигнал
до обработчиков asyncio — ранний обработчик: «Stopped cleaner before
startup», код 0.
+24 -9
View File
@@ -88,21 +88,36 @@ paths:
удаляется до ответа (`_compensate`: `delete_original` без повторов,
неудача — `warning`, исходная ошибка уходит дальше); сбой на
`commit()` — исход неизвестен, объект не трогается. `mark_ready` →
`None` (строку убрал уборщик) — `error`, удаление объекта, 503
`ServiceUnavailable`. После неудачного PUT компенсации нет, строку
`None` (строку убрал или пометил к уборке уборщик) — `error`,
удаление объекта, 503 `ServiceUnavailable`. После неудачного PUT
компенсации нет, строку
компенсация не удаляет никогда — её убирает уборщик. `CancelledError`
не ловится (`except Exception`);
- уборка — `AttachmentCleanupService(db_scope, storage)`
(`services/attachment_cleanup.py`), сервис процесса уборщика, а не
реплик API: `clean_stale_pending(*, older_than, batch_size,
stop_requested)`. Кандидаты — короткая транзакция без блокировки
(keyset), затем каждая строка — своя транзакция:
`lock_stale_pending` (`FOR UPDATE SKIP LOCKED`) → `delete_original`
→ `delete_attachment` → commit. Объект раньше строки: сбой между ними
оставляет строку без объекта, а не наоборот. Отказ S3 — откат
строки и прерывание прохода, отказ БД — тоже (`session_scope` уже
записал `warning`); `stop_requested()` проверяется перед строкой.
Итог — `CleanupPassDTO`;
(keyset), затем каждая строка — три шага (verify W1, design,
«Уточнения apply», п. 16):
1. транзакция пометки: `lock_stale_pending` (`FOR UPDATE SKIP
LOCKED`) → `mark_removing` (`updated_at = utcnow()`) → commit;
2. `delete_original` — вне транзакции, только после подтверждённой
пометки;
3. транзакция строки: снова `lock_stale_pending` →
`delete_attachment` → commit; строки нет или она занята —
пропуск.
Помеченную строку `mark_ready` в `ready` не переводит (`updated_at =
created_at`), поэтому сбой после удаления объекта (откат шага 3,
DELETE, который S3 выполнил после срока) не даёт `ready` без
объекта. Не одна транзакция на строку: её откат после удачного
DELETE в S3 вернул бы строку непомеченной, и загрузка, пережившая
grace, сделала бы её `ready` без объекта. Объект раньше строки: сбой
между ними оставляет строку без объекта, а не наоборот. Отказ S3 или
БД прерывает проход (`session_scope` уже записал `warning`),
помеченная строка ждёт следующего прохода — пометка ставится заново.
`stop_requested()` проверяется перед строкой и между шагами. Итог —
`CleanupPassDTO`;
- чтение: `pending`, нет строки, не участник — одно
`AttachmentNotFound`; скачивание — `open_original` вне транзакции,
нет объекта или другой размер — `error` в журнале и
+30 -7
View File
@@ -117,10 +117,18 @@ paths:
(замечание S6 verify `attachments`), `object-ids` (файлы `original`
из `weed shell fs.tree` под `/buckets/<bucket>/<база>/attachments`;
bucket и база — `FAULT_S3_BUCKET`, `FAULT_DATABASE` от
`run_failures.py`), `fail-attachments insert|ready|stall <filename>`
(триггер на уникальный `filename` теста: вставка или перевод в
`ready` падает с SQLSTATE 08006 — для API отказ БД, 503; `stall` —
перевод в `ready` ждёт `pg_sleep(4)`), `clear-fail-attachments`,
`run_failures.py`), `fail-attachments
insert|ready|stall|commit|outlive|undeletable <filename>` (триггеры
на уникальный `filename` теста, сбой — SQLSTATE 08006, для API отказ
БД, 503: вставка или перевод в `ready` падает; `stall` — перевод в
`ready` ждёт `pg_sleep(4)`; `commit` — отложенный триггер
ограничения роняет COMMIT перевода, исход для API неизвестен;
`outlive` — строка вставляется на час старше вместе с `updated_at`,
а перевод в `ready` ждёт до 4,5 с в триггере уровня оператора
`BEFORE UPDATE OF status`, пока строку не уберёт уборщик: на уровне
оператора строка не заблокирована, а пометку уборщика (только
`updated_at`) `OF status` не задерживает; `undeletable` — как
`outlive`, и удаление строки падает), `clear-fail-attachments`,
`kill-api` / `start-api` (`docker kill` / `docker start`
`<FAULT_PROJECT>-api`, ожидание `healthy`);
- тесты: `test_upload_with_object_storage_stopped` (+ «Незавершённая
@@ -134,7 +142,15 @@ paths:
(`stall` → строка и объект есть → `kill-api` → нет 201 → `start-api`
в `finally` → уборка), `test_cleaner_survives_outages` (S3 и
PostgreSQL остановлены, строка на месте после G + 3I, после возврата
S3 убрана за I + 5 с, готовое вложение цело). G и I —
S3 убрана за I + 5 с, готовое вложение цело); по замечаниям verify —
`test_ready_commit_outcome_unknown` (`commit`: 503, строка `pending`
и объект есть сразу после ответа, после G + I + 5 с ни того, ни
другого), `test_upload_outlives_grace` (`outlive`: 503, а не 201 и
не 500, ни строки, ни объекта) и
`test_cleaner_failure_after_object_delete` (`undeletable`: 503, а не
201, строка `pending`, `ready` без объекта нет; после снятия
триггера уборщик доводит уборку). Клиент загрузок с ожиданием в
триггере — со сроком 30 с (у `Api` по умолчанию 5 с). G и I —
`FAULT_CLEANER_GRACE_S` (20) и `FAULT_CLEANER_INTERVAL_S` (1) от
`run_failures.py`; запас поверх G + I — 5 с;
- красный прогон до кода (новые тесты против прежней ветки
@@ -142,7 +158,13 @@ paths:
`test_ready_failure_compensated` (объект остался),
`test_killed_between_put_and_ready`, `test_cleaner_survives_outages`,
`test_object_storage_paused` (строки никто не убрал); остальные
сценарии прежний код уже выполнял;
сценарии прежний код уже выполнял. Тесты по замечаниям verify:
`test_cleaner_failure_after_object_delete` красный на коде до пометки
(201: ждавший `mark_ready` перевёл строку в `ready` после отката
уборщика, объект уже удалён); `test_ready_commit_outcome_unknown` и
`test_upload_outlives_grace` на том коде зелёные (ветки были верны) и
красные на временных регрессиях — компенсация на любой сбой (объекта
нет сразу после 503) и возврат `RuntimeError` (500);
- исключения сверки: «Принявшая реплика остановлена» — `driver.py
attachment-failover` → `evidence/attachments/failover.md`; «Байты не в
БД и не на диске API» — `driver.py attachment-storage` →
@@ -223,7 +245,8 @@ paths:
compose и передаёт тестам (`FAULT_CLEANER_GRACE_S`,
`FAULT_CLEANER_INTERVAL_S`) и строкой `start cleaner: grace … s,
interval … s` в вывод. При падении печатается и журнал уборщика.
Прогон — ~3,5 мин (pytest ~190 с, было ~70 с);
Прогон — ~4 мин (32 проверки, pytest ~220 с; до `upload-consistency`
~70 с);
- `pytest -m fault`, затем журнал PostgreSQL стенда: сводка `postgres
log: N lines, crash markers M; "too many clients" X, "administrator
command" Y` после каждого прогона и ненулевой код при признаках
+8 -6
View File
@@ -131,8 +131,10 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore
загрузки убирает только уборщик — отдельный сервис `cleaner` на образе
API, а не реплики: строки `pending` старше `[cleaner]
pending_grace_seconds` (900 с; больше границы живой загрузки 17 с,
иначе уборщик не стартует) под `FOR UPDATE SKIP LOCKED`, объект раньше
строки, `ready` не трогает. У уборщика свой пользователь S3 — только
иначе уборщик не стартует) под `FOR UPDATE SKIP LOCKED`: сначала
пометка строки (`updated_at`) отдельной транзакцией, затем объект,
затем строка; помеченную строку `mark_ready` в `ready` не переводит,
`ready` уборщик не трогает. У уборщика свой пользователь S3 — только
чтение и удаление объектов своего bucket, ключи `S3_CLEANER_*` только
у него и bootstrap (`docker.md`, `settings.md`).
- `.env`, `config.toml`, секреты, токены и реальные данные не попадают ни
@@ -326,7 +328,7 @@ structlog (JSON в stdout), redis-py (клиент Valkey), aiobotocore
| `make wipe_data` | `down -v` — удалить данные стенда (volumes Postgres и S3 называются в запросе) и кэш; только после ввода `yes` |
| `make test_isolated [KEEP_TEST_DB=1]` | образ на временной базе `test_<db>` с Valkey и S3 стенда (ключи кэша и объектов разделены именем базы): сборка, миграции, отдельный контейнер API на `TEST_APP_PORT`, `make test` + `make student_test EXPECT_REPLICAS=1` (тесты реплик пропускаются с причиной), уборка при любом исходе — база и объекты под префиксом `test_<db>/` (`student-tests.md`) |
| `make student_test [BASE_URL=...] [EXPECT_REPLICAS=...]` | собственные тесты `student-tests/` (pytest) против запущенного сервера, кроме проверок отказов (`-m 'not fault'`); `EXPECT_REPLICAS` (по умолчанию `API_REPLICAS`) — сколько реплик за `BASE_URL`, против одного процесса — 1; сервер недоступен — код 2 и одна строка с адресом |
| `make failure_checks [FAULT_ARGS=...]` | проверки отказов (`pytest -m fault`, ~3,5 мин) на отдельном стенде: проект `<рабочий>-failures` со своими Postgres, Valkey и S3 (с bootstrap), уборщик (grace 20 с, интервал 1 с), обычный и «тесный» API (срок 2 с, пул 1), hook `student-tests/fault_hook.py`; после тестов — журнал PostgreSQL стенда: сводка (`crash markers`, «too many clients», «administrator command») и ненулевой код при признаках аварийного перезапуска; стенд и его volumes удаляются при любом исходе, рабочий не трогается (`student-tests.md`) |
| `make failure_checks [FAULT_ARGS=...]` | проверки отказов (`pytest -m fault`, ~4 мин) на отдельном стенде: проект `<рабочий>-failures` со своими Postgres, Valkey и S3 (с bootstrap), уборщик (grace 20 с, интервал 1 с), обычный и «тесный» API (срок 2 с, пул 1), hook `student-tests/fault_hook.py`; после тестов — журнал PostgreSQL стенда: сводка (`crash markers`, «too many clients», «administrator command») и ненулевой код при признаках аварийного перезапуска; стенд и его volumes удаляются при любом исходе, рабочий не трогается (`student-tests.md`) |
| `make bench [BENCH_LABEL=...]` | полная матрица 10k / 100k / 500k читаемого чата плюс 100 000 сообщений в 1 110 фоновых чатах разного размера (~35 мин, оценка по `bench_quick`) на своём проекте compose `mtusi-bench` (HAProxy и одна реплика API, Postgres, Valkey с лимитами, без портов хоста и без `.env` рабочего стенда; k6 ходит через LB); на каждый размер — свежий стенд, `VACUUM (ANALYZE)`, планы запроса истории (`auto_explain`) по уровням чатов с вариантами индекса и запроса, в конце — пробы стоимости записи по вариантам. Результаты в `evidence/bench/<метка>/`, занятая метка — отказ. Перед запуском — подготовка хоста (`bench.md`) |
| `make bench_quick` | самопроверка стенда на 1k / 5k / 10k и 3 500 фоновых сообщений (~3 мин), метка `quick-<время>`, в git не идёт |
| `make bench_restore [RESTORE_LABEL=...]` | трек 2, восстановление (~20 мин, метка `restore` по умолчанию): тот же стенд и данные, без матрицы прогонов; на каждый размер — `pg_dump` во время записи через HTTP, активность после backup, `pg_restore -j` в новый контейнер Postgres на новом volume, сверка обеих баз построчно, переключение API, проверки через HTTP до и после `FLUSHALL`; время dump / restore / RTO и потерянные сообщения — в `summary.md` |
@@ -370,12 +372,12 @@ src/
repos/<domain>.py # атомарный доступ к хранилищу, модульные функции
repos/idempotency.py # ключ идемпотентности: захват ON CONFLICT DO UPDATE WHERE просрочен, чтение сохранённого результата
repos/chat_cache.py # карточка чата в Valkey: ключ с именем базы, JSON ↔ ChatFullDTO
repos/attachment.py # строки вложений: вставка pending, mark_ready (pending → ready RETURNING), чтение одной и до 10; уборщику — get_stale_pending (keyset по частичному индексу), lock_stale_pending (FOR UPDATE SKIP LOCKED), delete_attachment
repos/attachment.py # строки вложений: вставка pending (created_at = updated_at), mark_ready (pending и непомеченная → ready RETURNING), чтение одной и до 10; уборщику — get_stale_pending (keyset по частичному индексу), lock_stale_pending (FOR UPDATE SKIP LOCKED), mark_removing (пометка updated_at), delete_attachment
repos/attachment_object.py # оригинал в S3: ключ <база>/attachments/<id>/original, put, open, delete_original
repos/message.py # MESSAGE_COLUMNS с ARRAY(подзапрос attachment_ids по position), вставка связей одной вставкой
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_cleanup.py # AttachmentCleanupService(db_scope, storage): проход уборщика — кандидаты keyset, каждая строка своей транзакцией: блокировка → DELETE объекта → DELETE строки; отказ S3 или БД прерывает проход; 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 пропавшего объекта
infra/
early_stop.py # ранний обработчик SIGTERM/SIGINT (только stdlib): до старта сервера — запись «Stopped <процесс> before startup» (API, cleaner) и выход 0; disarm() — первая строка lifespan; write_record — запись мимо structlog
@@ -412,7 +414,7 @@ student-tests/ # black-box тесты по HTTP (уровень 4)
test_failures.py # проверки отказов (маркер fault): только make failure_checks
run_isolated.py # make test_isolated: образ на временной базе test_<db>, уборка базы и префикса test_<db>/ в S3 (weed shell fs.rm, затем проверка fs.ls: код 0 weed shell успеха не значит; префикс только из проверенного имени) (stdlib)
run_failures.py # make failure_checks: стенд <рабочий>-failures (Postgres, Valkey, S3 + bootstrap, уборщик с grace 20 с и интервалом 1 с → FAULT_CLEANER_*), два API, pytest -m fault, журнал PostgreSQL стенда (сводка, признаки аварии — ненулевой код), журналы API и уборщика при падении, уборка (stdlib)
fault_hook.py # hook стенда отказов: stop/start/pause/unpause postgres|valkey|s3, кэш, триггеры сбоя участников, сообщений и вложений (fail-attachments insert|ready|stall), заполнение слотов max_connections, счётчик сессий PostgreSQL db-sessions, attachment-ids, last-pending, object-ids (файлы original по fs.tree), kill-api / start-api (stdlib)
fault_hook.py # hook стенда отказов: stop/start/pause/unpause postgres|valkey|s3, кэш, триггеры сбоя участников, сообщений и вложений (fail-attachments insert|ready|stall|commit|outlive|undeletable: сбой вставки, перевода в ready до и на COMMIT, задержка, строка «старше grace» с ожиданием уборщика, неудаляемая строка), заполнение слотов max_connections, счётчик сессий PostgreSQL db-sessions, attachment-ids, last-pending, object-ids (файлы original по fs.tree), kill-api / start-api (stdlib)
failures.compose.yml # override стенда отказов: без публикации портов (Postgres, Valkey, S3, LB), уборщик с CLEANER__* 20 / 1 и restart "no", stop_grace_period 2 с у S3, healthcheck PostgreSQL — на служебную базу postgres (не добавляет сессий в базу приложения), init: true у PostgreSQL (сирот psql из fill-connections подбирает init, а не postmaster)
bench/ # нагрузочный стенд на HAProxy + N реплик API + Postgres + Valkey: make bench / bench_quick / bench_restore / bench_failover / bench_rollout / bench_scaling
run.py # оркестратор: стенд compose, реплики и готовность по LB, фоновые чаты и расписание наполнения, матрица, обслуживание БД, планы и варианты, пробы записи, backup и восстановление во второе хранилище со сверкой, фазы профиля failover (события цели — поток docker events по контейнеру, а не буфер демона), профиль rollout (образ прежнего commit через git archive, scripts/rolling-update.sh против проекта стенда, поток событий Docker с exec_start), ресурсы профилей failover и rollout (Profile.sample_resources: сэмплер scan, карта контейнеров по меткам compose, окна, бюджет на пике, сторож), серии трека 1 (профили scaling_*, ячейки на свежем стенде, ступени k6 и поиск R*, сэмплер, продолжение RESUME, блокировка bench/.bench.lock), метрики (сумма по репликам), runs.csv / phases.csv / searches.csv / samples.csv / summary.md / meta.json
+28 -3
View File
@@ -804,9 +804,10 @@ design, «Уточнения apply», пп. 10–15):
- в консоли (`make run_dev`) уборщика нет.
3. **Проход** (решение 3): строка под `FOR UPDATE SKIP LOCKED` → DELETE
объекта → DELETE строки → commit. Блокировка упорядочивает уборщика и
`mark_ready` загрузки, пережившей grace, — `ready` без объекта не
появляется. Остаток риска: API заморожен дольше grace посреди PUT —
объект без строки, его находит сверка трека 2.
`mark_ready` загрузки, пережившей grace. Остаток риска: API заморожен
дольше grace посреди PUT — объект без строки, его находит сверка
трека 2. После verify — пометка строки отдельной транзакцией до
DELETE объекта (решение 18 ниже).
4. **Grace 900 с, интервал 60 с, выборка 100** (решение 4):
- граница живой загрузки от строки до `ready`: B = 2 × 6 + 5 = 17 с,
запас ×50;
@@ -866,6 +867,30 @@ apply»):
выполнявшееся поведение. Полный `make failure_checks` — 29 passed,
~3,5 мин.
Приняты 2026-10-21 в правках по verify (решения основной сессии;
design, «Уточнения apply», п. 16–20; tasks, группа 11):
18. **W1 — пометка строки до удаления объекта** вместо одной транзакции
уборщика: блокировка → `updated_at = utcnow()` → commit; DELETE
объекта; блокировка → DELETE строки → commit. `mark_ready` — только
при `updated_at = created_at`. Без миграции. Откат транзакции
уборщика после удачного DELETE в S3 больше не даёт `ready` без
объекта. Остаток — окно `make rolling_update` (прежние реплики и
уборщик) и объект без строки, если зомби дописал объект после
уборки, а компенсация не удалась.
19. **SIGTERM уборщика — между шагами строки**: три шага удлинили бы
худшую остановку до 17 с; доводится только текущий шаг (≤ 6 с).
Требование `graceful-shutdown` «Остановка уборщика» уточнено.
20. **W2, W3 — режимы hook `commit` и `outlive`** и тесты веток «исход
COMMIT неизвестен» и «строку убрал уборщик до `ready`»; W1 — режим
`undeletable`. Ожидание перевода в `ready` — триггер `BEFORE UPDATE
OF status` уровня оператора: пометку уборщика он не задерживает.
21. **Новые сценарии** — «Исход фиксации неизвестен» (`attachments`),
«Загрузка дольше grace» и «Сбой уборки после удаления объекта»
(`storage-consistency`), в дельтах и основных спеках.
22. **W4 и S1** — evidence «Отказ S3 во время прохода» с закоммиченного
кода; `docker.md` — `entrypoint` уборщика.
#### Вопросы
1. Как перенести секреты уборщика `S3_CLEANER_ACCESS_KEY` и
+131 -25
View File
@@ -204,16 +204,20 @@ cron-контейнер. Отвергнуты: ещё один образ, S3 и
(created_at, id) > (:after) ORDER BY created_at, id LIMIT
:batch_size`. Это keyset, как у истории, по частичному индексу
(решение 6). Занятая строка не возвращает проход к началу.
3. Каждый кандидат — своя транзакция:
1. `SELECT … WHERE id = :id AND status = 'pending' AND created_at <
:older_than FOR UPDATE SKIP LOCKED`. Нет строки — её уже убрали,
она стала `ready` или её держит другой процесс: пропуск;
2. `storage.delete(object_key)`: 204 и для отсутствующего объекта;
3. `DELETE FROM attachments WHERE id = :id`;
4. commit.
3. Каждый кандидат — три шага (после verify W1, «Уточнения apply»,
п. 16; было — одна транзакция с 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.
Отказ S3 откатывает транзакцию: строка остаётся, проход прерывается
(решение 5).
Отказ S3 прерывает проход: помеченная строка остаётся `pending`,
следующий проход ставит пометку заново (решение 5).
4. Итог — DTO: сколько убрано, сколько пропущено, причина прерывания,
длительность.
@@ -230,21 +234,40 @@ grace, после разморозки дойдёт до `mark_ready`. Без б
| | `DELETE … WHERE status = 'pending'` — 0 строк |
Итог — `ready` без объекта: клиент получил 201, скачивание — 500. С
блокировкой `mark_ready` ждёт commit уборщика и находит 0 строк. Ветка
`None` решения 1: 503 и удаление объекта. Если `mark_ready` успел
раньше, строка уже `ready`, и уборщик её не выбирает. Оба порядка
согласованы.
блокировкой `mark_ready` ждёт commit уборщика. Ветка `None` решения 1:
503 и удаление объекта. Если `mark_ready` успел раньше, строка уже
`ready`, и уборщик её не выбирает.
Транзакция держит блокировку и соединение уборщика на время DELETE в S3
(≤ 5 с). Это в своём пуле уборщика, на реплики не влияет. Сроки:
`[s3] timeout_seconds` (5) < `[database] request_timeout_seconds` (6) <
Одной блокировки мало (verify W1). В первой версии блокировка, DELETE
объекта и DELETE строки шли одной транзакцией, и её откат уже после
удачного DELETE в S3 возвращал строку `pending` в прежнем виде. Откат —
сбой БД перед COMMIT, срок 6 с, заморозка уборщика дольше
`idle_in_transaction_session_timeout`. То же, если DELETE в S3 истёк по
сроку, а сервер выполнил его позже. Ждавший `mark_ready` делал такую
строку `ready` без объекта (проба 3 verify). Поэтому пометка: уборщик
до DELETE объекта сдвигает `updated_at` отдельной зафиксированной
транзакцией, а `mark_ready` переводит в `ready` только строку с
`updated_at = created_at`. Вставка пишет оба поля одним значением
(`now`), а пометка — время уборщика, оно позже порога прохода и тем
более `created_at`. Помеченная строка `ready` уже не станет, и любой
исход шагов 2–3 оставляет её `pending`: загрузка получает `None` (503 и
компенсация), уборку доводит следующий проход. Миграции нет, CHECK
`updated_after_created` выполняется.
Блокировку и соединение уборщика держат только короткие транзакции
пометки и удаления строки; DELETE в S3 — между ними, вне транзакции.
Пул у уборщика свой, на реплики это не влияет. Сроки шага: `[s3]
timeout_seconds` (5) и `[database] request_timeout_seconds` (6) <
`idle_in_transaction_session_timeout` (10 с).
Остаток риска, назван в спеке и `REPORT.md`. Процесс API заморожен
дольше grace посреди PUT, уборщик убрал строку, затем после разморозки
S3 принял тело. Компенсации при этом нет: PUT для API завершился
ошибкой по сроку. Объект остаётся без строки, его находит только сверка
списком bucket (трек 2).
ошибкой по сроку. Или PUT прошёл, `mark_ready` получил `None`, а
удаление при компенсации не удалось. Объект остаётся без строки, его
находит только сверка списком bucket (трек 2). Второй остаток — окно
`make rolling_update` (п. 16): реплики прежней версии пометку не
проверяют.
*Альтернатива:* без блокировки, условие возраста в `mark_ready` (`AND
created_at > :deadline`). Отвергнута: API пришлось бы знать grace
@@ -558,17 +581,32 @@ Evidence (с закоммиченного кода):
## Risks / Trade-offs
- [Заморозка процесса API дольше grace посреди PUT оставляет объект без
строки] → вероятность — заморозка дольше 15 мин ровно посреди PUT;
запас grace ×50 над B; `error` в журнале у ветки `None`; находит сверка
трека 2. В спеке и `REPORT.md` названо прямо.
строки; то же — PUT прошёл после уборки, а удаление при компенсации не
удалось] → вероятность — заморозка дольше 15 мин ровно посреди PUT
(и для второго случая ещё отказ S3 на компенсации); запас grace ×50
над B; `error` в журнале у ветки `None`, `warning` «Attachment object
kept for cleaner»; находит сверка трека 2. В спеке и `REPORT.md`
названо прямо.
- [`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 с <
10 с `stop_grace_period`). Требование `graceful-shutdown` уточнено.
- [Компенсация добавляет до 5 с к ответу 503, если S3 стал медленным
после удачного PUT] → только ветка сбоя tx2. Худший путь загрузки и
так длиннее `timeout server` HAProxy (`attachments`, Risks). Пересмотр
цепочки — `upload-memory`.
- [Транзакция уборщика держит блокировку строки на время DELETE в S3
(≤ 5 с)] → только строки старше grace. `mark_ready` зомби-загрузки
подождёт — это и нужно. Пул уборщика свой (1 соединение); `idle_in_
transaction_session_timeout` 10 с больше срока S3 5 с.
- [Транзакции уборщика держат блокировку строки] → только короткие
транзакции пометки и удаления строки и только строки старше grace;
DELETE в S3 — между ними, вне транзакции (после verify W1).
`mark_ready` зомби-загрузки подождёт — это и нужно. Пул уборщика свой
(1 соединение).
- [Долгий отказ S3 копит строки `pending`: каждая попытка загрузки — одна
строка] → после возврата S3 уборщик убирает их выборками по 100 через
индекс. Стоимость обхода — трек 2.
@@ -744,3 +782,71 @@ stop cleaner`. Индекс и пользователь `cleaner` остаютс
код 137; с 0,05 с — «Stopped cleaner before startup», код 0 за 0,2 с.
То же ограничение, что у API (`run-modes.md`, «окно 0»), названо в
`REPORT.md`; данных не портит. В apply пауза 0,3 с его не задевала.
Правки по verify 2026-10-21 (0 CRITICAL, 4 WARNING, 1 SUGGESTION; решения
основной сессии, 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 =
created_at`, помеченная строка — `None`, то есть прежняя ветка
«строку убрал уборщик» (503 и компенсация). Проверено:
- вставка `pending` пишет оба поля одним `now` — и в текущем коде, и
в `d9d44c5` (`git show`): строки, вставленные прежними репликами,
новый `mark_ready` переводит в `ready` как раньше;
- пометка строго позже `created_at`: строка выбрана по `created_at <
older_than`, а `utcnow()` уборщика позже `older_than`;
- повтор после сбоя между транзакциями идемпотентен — пометка
ставится заново, следующий проход доводит строку;
- окно `make rolling_update`: реплики прежней версии (`f2dc0b3`)
условия не знают, а скрипт уборщика не пересоздаёт (прежний
уборщик не помечает). До конца замены и `docker compose up -d
--no-deps cleaner` остаётся прежний риск W1, это ограничение
(`balancer.md`, `REPORT.md`). Смешанные версии друг другу не
мешают: прежний уборщик с новыми репликами — поведение до правки,
новый уборщик с прежними репликами — тоже.
Три шага вместо одной транзакции удлиняют худший SIGTERM посреди
строки до 6 + 5 + 6 с при зависших хранилищах. Поэтому
`stop_requested()` проверяется и между шагами (доводится только
текущий, ≤ 6 с < 10 с), а требование `graceful-shutdown` «Остановка
уборщика» уточнено: «довести текущий шаг уборки … новых шагов не
начинать», в дельте и основном спеке. Попутно итог прохода называет
`interrupted_by="stop"` и после последней строки выборки (раньше —
`None`).
Тест — `test_cleaner_failure_after_object_delete`, режим hook
`undeletable` (вставка на час старше, ожидание перевода в `ready`,
удаление строки падает с 08006); сценарий «Сбой уборки после удаления
объекта» (`storage-consistency`, «Безопасность уборки»). Красный на
коде `f2dc0b3` (`make failure_checks FAULT_ARGS='-k "commit_outcome
or outlives or failure_after_object"'`: 1 failed, 2 passed) — 201
вместо 503 за 4,6 с: уборщик удалил объект, откатился на DELETE
строки, ждавший `mark_ready` перевёл её в `ready`. Зелёный полный
`make failure_checks` на новом коде — 32 passed за 222 с, вся
команда 239 с, журнал PostgreSQL без признаков аварии, стенд отказов
удалён.
17. **W2 — тест ветки «исход COMMIT неизвестен».** Режим hook `commit`:
`CREATE CONSTRAINT TRIGGER … AFTER UPDATE DEFERRABLE INITIALLY
DEFERRED`, 08006 на COMMIT перевода в `ready`. Тест
`test_ready_commit_outcome_unknown`, сценарий «Исход фиксации
неизвестен» (`attachments`, «Порядок записи»). На `f2dc0b3` зелёный
(код верен, как в пробе 1 verify); красный на временной регрессии
«компенсация на любой сбой» (`if not commit_sent` → всегда): объекта
нет сразу после 503. Правка возвращена (`git diff` файла пуст).
18. **W3 — тест ветки «строку убрал уборщик до `ready`».** Режим hook
`outlive`: вставка на час старше — `created_at` и `updated_at`
вместе, иначе после п. 16 строка выглядела бы помеченной и тест
проверял бы не ту ветку; ожидание перевода в `ready` до 4,5 с в
триггере уровня оператора, пока строка `pending` не исчезнет.
Триггер — `BEFORE UPDATE OF status`, а не любой `UPDATE`: пометка
уборщика меняет только `updated_at`, и общий триггер заставил бы
ждать и её (уборщик ждал бы исчезновения строки, которую сам держит,
до 4,5 с). Тест `test_upload_outlives_grace`, сценарий «Загрузка
дольше grace» (`storage-consistency`). На `f2dc0b3` зелёный; красный
на временном возврате `RuntimeError`: 500 вместо 503. Правка
возвращена.
19. **W4 — evidence «Отказ S3 во время прохода»** — после коммита
основной сессии (раздел в `evidence/attachments/cleaner-process.md`).
20. **S1** — `docker.md`, раздел «Уборщик»: `entrypoint`, как в
`docker-compose.yml`, и почему не `command` (п. 6).
@@ -28,9 +28,9 @@ S3: без зафиксированных метаданных объект не
уборщик;
- исход фиксации `ready` неизвестен: связь оборвалась во время
фиксации. API MUST NOT удалять объект — вложение могло стать `ready`;
- к шагу 4 метаданных «загружается» уже нет: их убрал уборщик, потому
что загрузка длилась дольше grace. Ответ SHALL быть 503
`unavailable`, и API SHALL удалить записанный объект.
- к шагу 4 метаданных «загружается» уже нет или уборщик уже начал их
уборку, потому что загрузка длилась дольше grace. Ответ SHALL быть
503 `unavailable`, и API SHALL удалить записанный объект.
Если запись метаданных на шаге 2 не удалась, объект MUST NOT
записываться; отказ PostgreSQL при этом — 503 `unavailable`. Загрузка,
@@ -76,6 +76,15 @@ S3: без зафиксированных метаданных объект не
- **AND** вложение остаётся в статусе «загружается» до уборщика, а по
API его не видно
#### Scenario: Исход фиксации неизвестен
- **WHEN** объект вложения записан в S3, а фиксация перевода в `ready`
обрывается отказом PostgreSQL
- **THEN** ответ 503 `unavailable`, вложение в статусе «загружается» и
по API не видно, а его объект в bucket остаётся: API его не удаляет
- **AND** после grace уборщик убирает и метаданные, и объект, а в bucket
нет объектов вложений без метаданных
#### Scenario: Обрыв передачи тела
- **WHEN** клиент обрывает соединение посреди тела загрузки
@@ -5,8 +5,10 @@
### Requirement: Остановка уборщика
По SIGTERM уборщик незавершённых загрузок (capability
`storage-consistency`) SHALL довести загрузку, которую убирает, до
конца или до отката и больше новых не брать. Затем он SHALL выйти с
`storage-consistency`) SHALL довести текущий шаг уборки загрузки до
конца или до отката и больше новых шагов не начинать. Загрузка,
остановленная между шагами, остаётся в состоянии, из которого её
доводит следующий проход. Затем он SHALL выйти с
кодом 0 раньше срока остановки контейнера (10 с), а не по SIGKILL.
Сигнал во время старта процесса SHALL завершать его с кодом 0 без
traceback, как у API (требование «Остановка во время старта»).
@@ -23,9 +23,11 @@
`[cleaner] interval_seconds`. Каждую загрузку, метаданные которой
записаны раньше чем `[cleaner] pending_grace_seconds` назад (grace
period), он SHALL убирать по шагам:
1. удалить объект по ключу из её метаданных; отсутствие объекта — не
1. пометить её метаданные как убираемые и зафиксировать пометку
(требование «Безопасность уборки»);
2. удалить объект по ключу из её метаданных; отсутствие объекта — не
ошибка;
2. только после подтверждённого удаления объекта — удалить метаданные.
3. только после подтверждённого удаления объекта — удалить метаданные.
Каждый шаг SHALL быть безопасно повторяемым: проход, прерванный на
любом шаге, доводит следующий. После уборки у вложения не остаётся ни
@@ -34,8 +36,10 @@ period), он SHALL убирать по шагам:
Ограничение называется в `REPORT.md`. Объект может остаться без
метаданных, если процесс API заморожен дольше grace посреди записи
объекта и после разморозки дописал объект уже убранной загрузки. Такой
объект находит только сверка bucket и БД (трек 2).
объекта и после разморозки дописал объект уже убранной загрузки, а
удалить его не смог: запись объекта завершилась для API ошибкой по
сроку, или не удалось удаление при компенсации. Такой объект находит
только сверка bucket и БД (трек 2).
#### Scenario: Зависшая загрузка убрана
@@ -68,11 +72,39 @@ PostgreSQL и запись объекта, у каждого свой срок (
Загрузка, которая длится дольше grace (процесс API заморожен), и
уборщик SHALL исключать друг друга на одном вложении. Исходов два:
- вложение стало `ready` вместе с объектом, и уборщик его не трогает;
- уборщик его убрал, а загрузка отвечает 503 `unavailable` и удаляет
записанный ею объект.
- уборщик начал его уборку, а загрузка отвечает 503 `unavailable` и
удаляет записанный ею объект.
Вложение `ready` без объекта MUST NOT появляться ни при каком порядке
этих действий.
До удаления объекта уборщик SHALL помечать метаданные вложения как
убираемые и фиксировать пометку отдельно. Помеченное вложение MUST NOT
становиться `ready`. Поэтому сбой уборки после удаления объекта не даёт
вложения `ready` без объекта: загрузка отвечает 503, а уборку доводит
следующий проход. Сбой — например, не удалось удалить метаданные, или
S3 выполнил удаление уже после срока вызова. Вложение `ready` без
объекта MUST NOT появляться ни при каком порядке этих действий.
Ограничение называется в `REPORT.md`. Пока идёт поочерёдная замена
реплик API, реплики прежней версии пометку не проверяют. Для их
загрузок, переживших grace, это свойство не гарантировано.
#### Scenario: Загрузка дольше grace
- **WHEN** загрузка записала объект, а к переводу в `ready` её
метаданным уже больше grace, и уборщик убирает их, пока загрузка ждёт
перевода
- **THEN** ответ 503 `unavailable`, а не 201 и не 500, нет ни
метаданных, ни объекта этого вложения, а в bucket нет объектов
вложений без метаданных
#### Scenario: Сбой уборки после удаления объекта
- **WHEN** загрузка ждёт перевода в `ready`, её метаданным больше grace,
а уборщик удалил её объект, но удалить метаданные не смог: PostgreSQL
отказал
- **THEN** ответ загрузки 503 `unavailable`, а не 201, метаданные в
статусе «загружается», и вложения `ready` без объекта нет
- **AND** когда удаление метаданных снова проходит, уборщик доводит
уборку, и в bucket нет объектов вложений без метаданных
#### Scenario: Свежая загрузка не тронута
@@ -339,3 +339,65 @@ exclusion».
таблицы доказательств есть команда, наблюдение и файл; `make lint`,
`make check`, `openspec validate upload-consistency --type change
--strict`. Коммит — после подтверждения.
## 11. Замечания проверки
Verify 2026-10-21: 0 CRITICAL, 4 WARNING, 1 SUGGESTION; решения
основной сессии — design, «Уточнения apply», п. 16–20. Новый или
изменённый сценарий правится и в дельте, и в основном спеке дословно.
- [x] 11.1 W1, «`ready` без объекта» при откате уборщика — закрыть кодом
(решение 3, «Уточнения apply», п. 16):
- уборщик: `lock_stale_pending` → пометка `updated_at = utcnow()`
(`mark_removing`) → commit; DELETE объекта; своя транзакция —
`lock_stale_pending` → `delete_attachment` → commit;
- `mark_ready` — только непомеченная строка (`updated_at =
created_at`), помеченная — `None` (503 и компенсация);
- требование «Безопасность уборки» (`storage-consistency`), сценарий
«Сбой уборки после удаления объекта», ограничение «Уборщика
незавершённых загрузок», Decisions и Risks design; окно `make
rolling_update`;
- режим hook `fail-attachments undeletable <filename>` и тест
`test_cleaner_failure_after_object_delete`.
Проверка: вставка `pending` пишет `created_at` и `updated_at` одним
значением (и в коде до change); красный прогон теста на коде до
правки (201 вместо 503), зелёный — после; полный `make failure_checks`.
- [x] 11.2 W2, «исход COMMIT неизвестен»: режим hook `fail-attachments
commit <filename>` (отложенный триггер ограничения, 08006), сценарий
«Исход фиксации неизвестен» (`attachments`), тест
`test_ready_commit_outcome_unknown`: 503, строка `pending`, объект
есть сразу после ответа; через G + I + 5 с ни строки, ни объекта,
объектов без строки нет. Проверка: тест красный на временной
регрессии «компенсация на любой сбой» (правка откатывается), зелёный
на коде.
- [x] 11.3 W3, «строку убрал уборщик до `ready`»: режим hook
`fail-attachments outlive <filename>` (вставка на час старше вместе с
`updated_at`, ожидание перевода в `ready` в триггере уровня оператора
`BEFORE UPDATE OF status`), сценарий «Загрузка дольше grace»
(`storage-consistency`), тест `test_upload_outlives_grace`: 503 (не
201 и не 500), ни строки, ни объекта, объектов без строки нет.
Проверка: тест красный на временном возврате `RuntimeError`, зелёный
на коде.
- [ ] 11.4 W4, evidence сценария `service-logging` «Отказ S3 во время
прохода» — раздел в `evidence/attachments/cleaner-process.md` (`pause
s3` → `cleaner --once` с grace 30 с: код 1, «Object storage is
unavailable» и «Interrupted cleanup pass» с `interrupted_by:
object_storage`, строка на месте → `unpause` → `--once` убирает) и
строка `REPORT.md`. Снимается с закоммиченного кода. Проверка: `grep`
секретов по `evidence/` пуст.
- [x] 11.5 S1: `.claude/rules/docker.md`, раздел «Уборщик» — `entrypoint`,
а не `command`. Проверка: текст совпадает с `docker-compose.yml`.
- [x] 11.6 Документы и регресс: правила (`service-layer.md`,
`repo-layer.md`, `student-tests.md`), AGENTS.md (карта кода, действия
hook, время `make failure_checks`), `PLAN.md`. Проверки: `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, `make test_isolated`,
`driver.py --port <LB> upload-consistency` (код 0).
- [ ] 11.7 После коммита основной сессии: evidence 11.4, пересъёмка
`evidence/tests/failure-checks.md` и чисел в `evidence/tests/` и
`REPORT.md`; `REPORT.md` — порядок уборки с пометкой и остаточный
риск, новые проверки, строка W4; строка этапа 3 `PLAN.md`.
+12 -3
View File
@@ -403,9 +403,9 @@ S3: без зафиксированных метаданных объект не
уборщик;
- исход фиксации `ready` неизвестен: связь оборвалась во время
фиксации. API MUST NOT удалять объект — вложение могло стать `ready`;
- к шагу 4 метаданных «загружается» уже нет: их убрал уборщик, потому
что загрузка длилась дольше grace. Ответ SHALL быть 503
`unavailable`, и API SHALL удалить записанный объект.
- к шагу 4 метаданных «загружается» уже нет или уборщик уже начал их
уборку, потому что загрузка длилась дольше grace. Ответ SHALL быть
503 `unavailable`, и API SHALL удалить записанный объект.
Если запись метаданных на шаге 2 не удалась, объект MUST NOT
записываться; отказ PostgreSQL при этом — 503 `unavailable`. Загрузка,
@@ -451,6 +451,15 @@ S3: без зафиксированных метаданных объект не
- **AND** вложение остаётся в статусе «загружается» до уборщика, а по
API его не видно
#### Scenario: Исход фиксации неизвестен
- **WHEN** объект вложения записан в S3, а фиксация перевода в `ready`
обрывается отказом PostgreSQL
- **THEN** ответ 503 `unavailable`, вложение в статусе «загружается» и
по API не видно, а его объект в bucket остаётся: API его не удаляет
- **AND** после grace уборщик убирает и метаданные, и объект, а в bucket
нет объектов вложений без метаданных
#### Scenario: Обрыв передачи тела
- **WHEN** клиент обрывает соединение посреди тела загрузки
+4 -2
View File
@@ -196,8 +196,10 @@ SIGTERM и SIGINT, пришедшие процессу сервиса во вр
### Requirement: Остановка уборщика
По SIGTERM уборщик незавершённых загрузок (capability
`storage-consistency`) SHALL довести загрузку, которую убирает, до
конца или до отката и больше новых не брать. Затем он SHALL выйти с
`storage-consistency`) SHALL довести текущий шаг уборки загрузки до
конца или до отката и больше новых шагов не начинать. Загрузка,
остановленная между шагами, остаётся в состоянии, из которого её
доводит следующий проход. Затем он SHALL выйти с
кодом 0 раньше срока остановки контейнера (10 с), а не по SIGKILL.
Сигнал во время старта процесса SHALL завершать его с кодом 0 без
traceback, как у API (требование «Остановка во время старта»).
+40 -8
View File
@@ -23,9 +23,11 @@
`[cleaner] interval_seconds`. Каждую загрузку, метаданные которой
записаны раньше чем `[cleaner] pending_grace_seconds` назад (grace
period), он SHALL убирать по шагам:
1. удалить объект по ключу из её метаданных; отсутствие объекта — не
1. пометить её метаданные как убираемые и зафиксировать пометку
(требование «Безопасность уборки»);
2. удалить объект по ключу из её метаданных; отсутствие объекта — не
ошибка;
2. только после подтверждённого удаления объекта — удалить метаданные.
3. только после подтверждённого удаления объекта — удалить метаданные.
Каждый шаг SHALL быть безопасно повторяемым: проход, прерванный на
любом шаге, доводит следующий. После уборки у вложения не остаётся ни
@@ -34,8 +36,10 @@ period), он SHALL убирать по шагам:
Ограничение называется в `REPORT.md`. Объект может остаться без
метаданных, если процесс API заморожен дольше grace посреди записи
объекта и после разморозки дописал объект уже убранной загрузки. Такой
объект находит только сверка bucket и БД (трек 2).
объекта и после разморозки дописал объект уже убранной загрузки, а
удалить его не смог: запись объекта завершилась для API ошибкой по
сроку, или не удалось удаление при компенсации. Такой объект находит
только сверка bucket и БД (трек 2).
#### Scenario: Зависшая загрузка убрана
@@ -68,11 +72,39 @@ PostgreSQL и запись объекта, у каждого свой срок (
Загрузка, которая длится дольше grace (процесс API заморожен), и
уборщик SHALL исключать друг друга на одном вложении. Исходов два:
- вложение стало `ready` вместе с объектом, и уборщик его не трогает;
- уборщик его убрал, а загрузка отвечает 503 `unavailable` и удаляет
записанный ею объект.
- уборщик начал его уборку, а загрузка отвечает 503 `unavailable` и
удаляет записанный ею объект.
Вложение `ready` без объекта MUST NOT появляться ни при каком порядке
этих действий.
До удаления объекта уборщик SHALL помечать метаданные вложения как
убираемые и фиксировать пометку отдельно. Помеченное вложение MUST NOT
становиться `ready`. Поэтому сбой уборки после удаления объекта не даёт
вложения `ready` без объекта: загрузка отвечает 503, а уборку доводит
следующий проход. Сбой — например, не удалось удалить метаданные, или
S3 выполнил удаление уже после срока вызова. Вложение `ready` без
объекта MUST NOT появляться ни при каком порядке этих действий.
Ограничение называется в `REPORT.md`. Пока идёт поочерёдная замена
реплик API, реплики прежней версии пометку не проверяют. Для их
загрузок, переживших grace, это свойство не гарантировано.
#### Scenario: Загрузка дольше grace
- **WHEN** загрузка записала объект, а к переводу в `ready` её
метаданным уже больше grace, и уборщик убирает их, пока загрузка ждёт
перевода
- **THEN** ответ 503 `unavailable`, а не 201 и не 500, нет ни
метаданных, ни объекта этого вложения, а в bucket нет объектов
вложений без метаданных
#### Scenario: Сбой уборки после удаления объекта
- **WHEN** загрузка ждёт перевода в `ready`, её метаданным больше grace,
а уборщик удалил её объект, но удалить метаданные не смог: PostgreSQL
отказал
- **THEN** ответ загрузки 503 `unavailable`, а не 201, метаданные в
статусе «загружается», и вложения `ready` без объекта нет
- **AND** когда удаление метаданных снова проходит, уборщик доводит
уборку, и в bucket нет объектов вложений без метаданных
#### Scenario: Свежая загрузка не тронута
+31 -2
View File
@@ -3,7 +3,7 @@
Строка пишется в статусе `pending` до записи объекта и переводится в
`ready` после неё (design change `attachments`, решение 1). Видимость
`pending` решает сервис: repo отдаёт строку как есть. Незавершённые
загрузки выбирает, блокирует и удаляет уборщик (design change
загрузки выбирает, блокирует, помечает и удаляет уборщик (design change
`upload-consistency`, решение 3).
"""
@@ -79,12 +79,20 @@ async def mark_ready(
attachment_id: UUID,
updated_at: datetime,
) -> dataclasses.AttachmentFullDTO | None:
"""`pending` → `ready`; `None` — строки в статусе `pending` нет."""
"""`pending` → `ready`; `None` — строки `pending` нет или уборщик уже
пометил её к уборке.
Вставка пишет `created_at` и `updated_at` одним значением, а уборщик
до удаления объекта сдвигает `updated_at` (`mark_removing`): `ready`
становится только непомеченная строка (design change
`upload-consistency`, «Уточнения apply», п. 16).
"""
statement = (
update(Attachment)
.where(
Attachment.id == attachment_id,
Attachment.status == AttachmentStatus.PENDING.value,
Attachment.updated_at == Attachment.created_at,
)
.values(status=AttachmentStatus.READY.value, updated_at=updated_at)
.returning(*_ATTACHMENT_COLUMNS)
@@ -182,6 +190,27 @@ async def lock_stale_pending(
)
async def mark_removing(
db_session: AsyncSession,
*,
attachment_id: UUID,
updated_at: datetime,
) -> bool:
"""Пометить строку к уборке: `updated_at` позже `created_at`, и
`mark_ready` её больше не переведёт в `ready`. `False` — строки нет.
Вызывается под блокировкой `lock_stale_pending`: `created_at` строки
раньше порога прохода, а `updated_at` — время уборщика после него.
"""
statement = (
update(Attachment)
.where(Attachment.id == attachment_id)
.values(updated_at=updated_at)
.returning(Attachment.id)
)
return (await db_session.execute(statement)).one_or_none() is not None
async def delete_attachment(
db_session: AsyncSession,
*,
+51 -13
View File
@@ -2,10 +2,11 @@
решения 3 и 5).
Сервис процесса уборщика (`src/cleaner/`), а не реплик API. Строка
`pending` старше grace: блокировка `FOR UPDATE SKIP LOCKED` → удаление
объекта → удаление строки → commit, каждая строка — своя транзакция.
Метаданные удаляются последними: объекта без строки уборка не
оставляет. Строки `ready` выборка не видит.
`pending` старше grace: блокировка `FOR UPDATE SKIP LOCKED` → пометка
(`updated_at`) → commit → удаление объекта → блокировка → удаление
строки → commit. Метаданные удаляются последними: объекта без строки
уборка не оставляет. Строки `ready` выборка не видит, а помеченную
строку `mark_ready` в `ready` не переводит («Уточнения apply», п. 16).
"""
import time
@@ -85,12 +86,16 @@ class AttachmentCleanupService:
if await self._remove(
attachment_id=candidate.id,
older_than=older_than,
stop_requested=stop_requested,
log=log,
):
removed += 1
else:
skipped += 1
if len(candidates) < batch_size or stop_requested():
if stop_requested():
# и после последней строки выборки, и посреди строки
interrupted_by = INTERRUPTED_BY_STOP
if len(candidates) < batch_size:
break
after = (candidates[-1].created_at, candidates[-1].id)
except exceptions.ObjectStorageUnavailable:
@@ -127,14 +132,29 @@ class AttachmentCleanupService:
*,
attachment_id: UUID,
older_than: datetime,
stop_requested: Callable[[], bool],
log: AbstractLogger,
) -> bool:
"""Убрать одну строку; `False` — её уже нет, она `ready` или её
держит другой процесс.
Блокировка строки упорядочивает уборщика и `mark_ready` загрузки,
пережившей grace: та ждёт commit и находит 0 строк (решение 3).
Объект — до строки; отказ S3 откатывает транзакцию.
1. Пометка — своя транзакция: блокировка, `updated_at` = сейчас,
commit. Загрузка, пережившая grace, ждёт блокировку в
`mark_ready` и после commit находит строку помеченной: `None`,
503 и компенсация. После пометки строка `ready` уже не станет,
поэтому никакой исход следующих шагов не даёт `ready` без
объекта: ни откат удаления строки, ни DELETE, который S3
выполнил после срока вызова (verify W1).
2. Объект — вне транзакции, после подтверждённой пометки. Отказ
S3 прерывает проход, помеченная строка ждёт следующего.
3. Строка — своя транзакция с той же блокировкой; занята или уже
убрана — пропуск, следующий проход доводит.
Повтор после сбоя между шагами идемпотентен: пометка ставится
заново, удаление объекта и строки — те же. `stop_requested()`
проверяется и между шагами: по SIGTERM доводится только текущий
шаг (не дольше срока шага с БД, 6 с), и уборщик укладывается в
срок остановки контейнера (10 с); помеченная строка ждёт
следующего запуска.
"""
async with self.db_scope() as db_session:
stale = await attachment_repo.lock_stale_pending(
@@ -144,13 +164,31 @@ class AttachmentCleanupService:
)
if stale is None:
return False
await attachment_object_repo.delete_original(
self.storage,
key=stale.object_key,
)
await attachment_repo.delete_attachment(
await attachment_repo.mark_removing(
db_session=db_session,
attachment_id=stale.id,
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:
locked = await attachment_repo.lock_stale_pending(
db_session=db_session,
attachment_id=stale.id,
older_than=older_than,
)
if locked is None:
return False
await attachment_repo.delete_attachment(
db_session=db_session,
attachment_id=locked.id,
)
await db_session.commit()
log.info(
+99 -17
View File
@@ -39,13 +39,19 @@
s3). Каталог `<id>` без файла не считается:
после DELETE SeaweedFS убирает его лишь
через ~2 мин
fail-attachments insert|ready|stall <filename>
триггер на вложения с этим filename:
insert — вставка строки падает, ready —
перевод в ready падает (оба с SQLSTATE 08006,
для API это отказ БД, 503); stall — перевод
в ready ждёт pg_sleep(4)
clear-fail-attachments убрать триггер
fail-attachments insert|ready|stall|commit|outlive|undeletable <filename>
триггеры на вложения с этим filename (сбой —
SQLSTATE 08006, для API это отказ БД, 503):
insert — вставка строки падает; ready —
перевод в ready падает до COMMIT; stall —
перевод в ready ждёт pg_sleep(4); commit —
перевод в ready падает на COMMIT (исход для
API неизвестен); outlive — строка
вставляется на час старше (уборщик берёт её
сразу), а перевод в ready ждёт до 4,5 с, пока
строка pending не исчезнет; undeletable — как
outlive, и удаление строки падает
clear-fail-attachments убрать триггеры
kill-api docker kill обычного API стенда
(`<FAULT_PROJECT>-api`)
start-api docker start того же контейнера и ожидание
@@ -202,23 +208,49 @@ LAST_PENDING_SQL = """\
SELECT id FROM attachments WHERE status = 'pending'
ORDER BY created_at DESC, id DESC LIMIT 1;
"""
# режим и filename — аргументы триггера (TG_ARGV). SQLSTATE 08006
# режим и filename — аргументы триггеров (TG_ARGV). SQLSTATE 08006
# (connection_failure) приложение считает отказом БД: 503, а не 500
# (design change upload-consistency, пробы). stall — меньше
# statement_timeout (5 с): ожидание завершается само
# (design change upload-consistency, пробы). Три триггера, каждый
# срабатывает только в своих режимах:
# - fault_fail_attachments (строка, BEFORE): insert, ready, stall; в outlive
# и undeletable вставка «на час старше» — created_at и updated_at вместе,
# строка остаётся непомеченной (mark_ready требует updated_at =
# created_at); в undeletable удаление строки падает;
# - fault_fail_attachments_commit (отложенный триггер ограничения, AFTER
# UPDATE): commit — перевод в ready падает на COMMIT, исход для API
# неизвестен;
# - fault_wait_attachments (оператор, BEFORE UPDATE OF status): outlive и
# undeletable — перевод в ready ждёт, пока строка pending с этим
# filename не исчезнет, но не дольше WAIT. На уровне оператора строка ещё
# не заблокирована, уборщик её берёт. UPDATE OF status: пометку уборщика
# (меняет только updated_at) ожидание не задерживает.
# stall и ожидание короче statement_timeout (5 с): завершаются сами
FAIL_ATTACHMENTS_SQL = """\
CREATE OR REPLACE FUNCTION fault_fail_attachments() RETURNS trigger
LANGUAGE plpgsql AS $$
BEGIN
IF TG_OP = 'DELETE' THEN
IF OLD.filename = TG_ARGV[1] AND TG_ARGV[0] = 'undeletable' THEN
RAISE EXCEPTION 'fault injected: attachment delete'
USING ERRCODE = '08006';
END IF;
RETURN OLD;
END IF;
IF NEW.filename <> TG_ARGV[1] THEN
RETURN NEW;
END IF;
IF TG_OP = 'INSERT' AND TG_ARGV[0] = 'insert' THEN
RAISE EXCEPTION 'fault injected: attachment insert'
USING ERRCODE = '08006';
IF TG_OP = 'INSERT' THEN
IF TG_ARGV[0] = 'insert' THEN
RAISE EXCEPTION 'fault injected: attachment insert'
USING ERRCODE = '08006';
END IF;
IF TG_ARGV[0] IN ('outlive', 'undeletable') THEN
NEW.created_at := NEW.created_at - interval '1 hour';
NEW.updated_at := NEW.updated_at - interval '1 hour';
END IF;
RETURN NEW;
END IF;
IF TG_OP = 'UPDATE' AND OLD.status = 'pending'
AND NEW.status = 'ready' THEN
IF OLD.status = 'pending' AND NEW.status = 'ready' THEN
IF TG_ARGV[0] = 'ready' THEN
RAISE EXCEPTION 'fault injected: attachment ready'
USING ERRCODE = '08006';
@@ -230,15 +262,65 @@ BEGIN
RETURN NEW;
END
$$;
CREATE OR REPLACE FUNCTION fault_fail_attachments_commit() RETURNS trigger
LANGUAGE plpgsql AS $$
BEGIN
IF TG_ARGV[0] = 'commit' AND NEW.filename = TG_ARGV[1]
AND OLD.status = 'pending' AND NEW.status = 'ready' THEN
RAISE EXCEPTION 'fault injected: attachment ready commit'
USING ERRCODE = '08006';
END IF;
RETURN NULL;
END
$$;
CREATE OR REPLACE FUNCTION fault_wait_attachments() RETURNS trigger
LANGUAGE plpgsql AS $$
DECLARE
deadline timestamptz := clock_timestamp() + interval '4.5 seconds';
BEGIN
IF TG_ARGV[0] NOT IN ('outlive', 'undeletable') THEN
RETURN NULL;
END IF;
WHILE clock_timestamp() < deadline AND EXISTS (
SELECT 1 FROM attachments
WHERE filename = TG_ARGV[1] AND status = 'pending'
) LOOP
PERFORM pg_sleep(0.1);
END LOOP;
RETURN NULL;
END
$$;
DROP TRIGGER IF EXISTS fault_fail_attachments ON attachments;
CREATE TRIGGER fault_fail_attachments BEFORE INSERT OR UPDATE ON attachments
CREATE TRIGGER fault_fail_attachments
BEFORE INSERT OR UPDATE OR DELETE ON attachments
FOR EACH ROW EXECUTE FUNCTION fault_fail_attachments(:'mode', :'title');
DROP TRIGGER IF EXISTS fault_fail_attachments_commit ON attachments;
CREATE CONSTRAINT TRIGGER fault_fail_attachments_commit
AFTER UPDATE ON attachments DEFERRABLE INITIALLY DEFERRED
FOR EACH ROW
EXECUTE FUNCTION fault_fail_attachments_commit(:'mode', :'title');
DROP TRIGGER IF EXISTS fault_wait_attachments ON attachments;
CREATE TRIGGER fault_wait_attachments
BEFORE UPDATE OF status ON attachments
FOR EACH STATEMENT
EXECUTE FUNCTION fault_wait_attachments(:'mode', :'title');
"""
CLEAR_FAIL_ATTACHMENTS_SQL = """\
DROP TRIGGER IF EXISTS fault_fail_attachments ON attachments;
DROP TRIGGER IF EXISTS fault_fail_attachments_commit ON attachments;
DROP TRIGGER IF EXISTS fault_wait_attachments ON attachments;
DROP FUNCTION IF EXISTS fault_fail_attachments();
DROP FUNCTION IF EXISTS fault_fail_attachments_commit();
DROP FUNCTION IF EXISTS fault_wait_attachments();
"""
FAIL_ATTACHMENTS_MODES = ("insert", "ready", "stall")
FAIL_ATTACHMENTS_MODES = (
"insert",
"ready",
"stall",
"commit",
"outlive",
"undeletable",
)
# как S3_BUCKET_NAME_PATTERN в src/utils/constants.py; имя базы — как в
# run_isolated.py: путь filer собирается только из проверенных имён
BUCKET_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$")
+111
View File
@@ -575,6 +575,12 @@ def orphan_objects(stand: Stand) -> set[str]:
return stored_ids(stand) - set(rows)
def ready_without_object(stand: Stand) -> set[str]:
"""Готовые вложения без объекта: строки `ready` уборщик не трогает,
поэтому порядок вызовов здесь не важен."""
return ready_ids(attachment_rows(stand)) - stored_ids(stand)
def new_ids(before: dict[str, str], after: dict[str, str]) -> set[str]:
return set(after) - set(before)
@@ -875,6 +881,111 @@ def test_killed_between_put_and_ready(
api.upload(alice, chat["id"], images.sample_png())
@pytest.mark.spec("attachments", "Исход фиксации неизвестен")
def test_ready_commit_outcome_unknown(
api: Api,
stand: Stand,
alice: Actor,
chat: dict[str, Any],
) -> None:
"""Перевод в ready падает на самом COMMIT (отложенный триггер): API не
знает, зафиксировано ли вложение, и объект не трогает (verify W2)."""
filename = fault_filename()
before = attachment_rows(stand)
stand("fail-attachments", "commit", filename)
try:
started = time.monotonic()
resp = upload_raw(
api,
alice,
chat,
images.sample_png(),
filename=filename,
)
assert_error(resp, 503)
finally:
stand("clear-fail-attachments")
after = attachment_rows(stand)
(pending,) = new_ids(before, after)
assert after[pending] == "pending"
# компенсации нет: вложение могло стать ready
assert pending in stored_ids(stand)
assert_invisible(api, alice, chat, pending)
wait_cleaned(stand, pending, since=started)
assert not orphan_objects(stand)
@pytest.mark.spec("storage-consistency", "Загрузка дольше grace")
def test_upload_outlives_grace(
api: Api,
stand: Stand,
alice: Actor,
chat: dict[str, Any],
) -> None:
"""Строка вставлена «на час старше», перевод в ready ждёт в триггере,
пока её не уберёт уборщик стенда: загрузка, пережившая grace, без
заморозки процесса (verify W3)."""
filename = fault_filename()
before = attachment_rows(stand)
stand("fail-attachments", "outlive", filename)
# ожидание в триггере до 4,5 с: срок клиента больше
slow = Api(str(api.client.base_url), timeout=THREAD_CLIENT_TIMEOUT_S)
try:
with slow:
resp = upload_raw(
slow,
alice,
chat,
images.sample_png(),
filename=filename,
)
# не 201 (ready без объекта) и не 500 (дефект ветки)
assert_error(resp, 503)
finally:
stand("clear-fail-attachments")
rows = attachment_rows(stand)
assert not new_ids(before, rows), rows
assert not stored_ids(stand) - set(before)
assert not orphan_objects(stand)
@pytest.mark.spec("storage-consistency", "Сбой уборки после удаления объекта")
def test_cleaner_failure_after_object_delete(
api: Api,
stand: Stand,
alice: Actor,
chat: dict[str, Any],
) -> None:
"""Уборщик удалил объект, а удаление строки упало (08006), пока загрузка
ждёт перевода в ready: строка помечена до удаления объекта и ready уже
не станет (verify W1)."""
filename = fault_filename()
before = attachment_rows(stand)
stand("fail-attachments", "undeletable", filename)
slow = Api(str(api.client.base_url), timeout=THREAD_CLIENT_TIMEOUT_S)
try:
with slow:
resp = upload_raw(
slow,
alice,
chat,
images.sample_png(),
filename=filename,
)
assert_error(resp, 503)
(pending,) = new_ids(before, attachment_rows(stand))
assert attachment_rows(stand).get(pending) == "pending"
assert not ready_without_object(stand)
assert_invisible(api, alice, chat, pending)
finally:
stand("clear-fail-attachments")
# строка старше grace: следующий проход доводит уборку
returned = time.monotonic()
wait_cleaned(stand, pending, since=returned - CLEANER_GRACE_S)
assert not orphan_objects(stand)
assert not ready_without_object(stand)
@pytest.mark.spec("storage-consistency", "S3 недоступен во время уборки")
@pytest.mark.spec("storage-consistency", "БД недоступна во время уборки")
@pytest.mark.spec("storage-consistency", "Готовые вложения не тронуты")