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>
26 KiB
Tasks
Как строить — design.md (дальше «решение N»), что должно получиться —
дельты в specs/. Перед первым файлом слоя прочитать его правило:
service-layer.md, repo-layer.md, dto.md, infra.md,
migrations.md, logging.md, settings.md, run-modes.md,
docker.md, balancer.md, student-tests.md, bench.md. Evidence
снимается с закоммиченного кода, коммит — только после подтверждения
пользователя (bench.md, «Измеренное состояние — commit»).
Шаг оператора до группы 5 — заменён в apply ответом основной
сессии (PLAN.md, ### upload-consistency → «Вопросы», п. 1):
make env_setup сам дописывает недостающие переменные шаблона в
существующий .env (design, «Уточнения apply», п. 1). Прежний текст:
в рабочий .env нужно перенести строки
S3_CLEANER_ACCESS_KEY и S3_CLEANER_SECRET_KEY из .env.example,
секреты — openssl rand -hex 10 и openssl rand -hex 20. Делает это
пользователь (PLAN.md, ### upload-consistency → «Вопросы», п. 1).
Агент .env не читает и не правит. До переноса любая команда compose
останавливается на :?: и рабочий стенд, и make failure_checks, и
make test_isolated.
Ожидаемо красное по ходу работы, остальное разбирается по AGENTS.md:
между задачами 6.3 и 6.4 (sync дельт) сверка покрытия в make student_test падает на маркерах новых сценариев: «marker points to
unknown scenario». Sync раньше тестов дал бы обратное — «no test and no
exclusion».
1. Настройки, общий контекст сессии, ранний обработчик
-
1.1 Секция
[cleaner]по решению 4 и дельтеservice-configuration:- класс
Cleanerвsrc/config/settings.py:interval_seconds(float, > 0, 60),pending_grace_seconds(int, > 0, 900),batch_size(int, ≥ 1, 100); - строки с комментариями единиц в
config_example.toml.
Проверка:
uv run python -c "from src.config import settings; print(settings.cleaner)"— значения по умолчанию;CLEANER__INTERVAL_SECONDS=0— ошибка проверки настроек называетinterval_seconds. - класс
-
1.2 Общий контекст сессии по решению 7. Функция
session_scope(session_factory, *, timeout_seconds)вsrc/infra/db/с телом нынешнегоdb_session_scope: срок,is_db_unavailable→invalidate(),warning,ServiceUnavailable.db_session_scopeиget_db_sessionвsrc/api/dependencies.pyстановятся обёртками над ней с фабрикой процесса API. Проверка:make lint; поведение API — группа 6 и задача 8.1, итоги прежних тестов те же. -
1.3
src/infra/early_stop.py: имя процесса в записи «Stopped … before startup», по умолчанию — прежний текст API (решение 2). Проверка:make lint;driver.py stop-at-start— запись API прежняя («Stopped API before startup»), код 0; уборщик — задача 5.3.
2. Схема: частичный индекс
-
2.1 Индекс по решению 6:
Index(..., postgresql_where=...)по(created_at, id)в моделиAttachment;- ревизия поверх
ef25d50b01a8руками:autocommit_block,SET lock_timeout = '2s',create_index(..., postgresql_concurrently=True, if_not_exists=True),RESET lock_timeout; downgrade—drop_index(..., postgresql_concurrently=True, if_exists=True).
Проверка:
uv run alembic upgrade head --sql—CREATE INDEX CONCURRENTLY IF NOT EXISTSвнеBEGIN … COMMITпрежних ревизий;- временная база (
createdbв контейнереpostgres,DATABASE__NAMEв окружении):upgradeс нуля → повтор без изменений →downgrade -1→upgrade, затемDROP DATABASE; pg_index.indisvalid— true;- на рабочей базе в транзакции с откатом: несколько тысяч строк
pendingиready→EXPLAIN (ANALYZE, BUFFERS)выборки кандидатов решения 3 —Index Scanпоix_attachments_pending_created_at. Итог — в design, «Уточнения apply».
3. Repo и сервисы
-
3.1 Repo по решению 3, в каждой функции одно выражение:
src/core/repos/attachment.py: выборка кандидатов (keyset по(created_at, id),status = 'pending',created_at < :older_than,LIMIT); блокировка одного кандидата (FOR UPDATE SKIP LOCKEDс теми же условиями); удаление строки;src/core/repos/attachment_object.py:delete_original.
Проверка:
make lint; поведение — группы 5 и 6. -
3.2
AttachmentService.uploadпо решению 1:- флаг «COMMIT отправлен» вокруг
mark_readyиcommit(); - компенсация (
delete_original, без повторов) при сбое tx2 до COMMIT и приmark_ready→None; None—ServiceUnavailableиerrorвместоRuntimeError;- записи журнала по решению 1, без
filename.
Проверка:
make lint; по HTTP — тесты 6.3 «Фиксация ready не удалась» и «Объект без фиксации убран», драйвер 7.1. - флаг «COMMIT отправлен» вокруг
-
3.3 Сервис уборки
AttachmentCleanupService(db_scope, storage)вsrc/core/services/attachment_cleanup.pyпо решениям 3 и 5:- проход
clean_stale_pending(*, older_than, batch_size): каждая строка — своя транзакция, сначала объект, потом строка; - отказ S3 прерывает проход, отказ БД его пропускает;
- DTO итога прохода в
src/schemas/dataclasses/attachment.pyпоdto.md; - журнал по дельте
service-logging.
Проверка:
make lint; поведение — группы 5 и 6. - проход
4. Процесс уборщика
-
4.1 Пакет
src/cleaner/по решениям 2, 4 и 5:__main__.py— ранний обработчик с именем процесса, затемmain();main.py:- проверка grace против
2 × request_timeout_seconds + s3.timeout_seconds, иначеerrorи код 2; - свой engine и
session_scope, клиент S3 с namespace — именем базы; - цикл с ожиданием интервала или сигнала, обработчики SIGTERM и SIGINT в asyncio;
--onceс кодами 0, 1, 2;- записи «Started cleaner» (интервал, grace, выборка, адрес S3, bucket, база) и «Stopped cleaner».
- проверка grace против
Проверка без стенда:
CLEANER__PENDING_GRACE_SECONDS=17 uv run python -m src.cleaner --once— код 2, ошибка называет grace, оба срока и границу 17 с, к БД и S3 нет ни одного обращения;CLEANER__INTERVAL_SECONDS=abc— ошибка проверки настроек;make lint.
5. Стенд
-
5.1 Секреты уборщика по решению 8:
- строки
S3_CLEANER_ACCESS_KEY,S3_CLEANER_SECRET_KEYс комментарием в.env.example; ENV_SECRETSи замены вmake env_setup;- шапка шаблона — «шесть секретов S3».
Проверка: подстановки рецепта
env_setupдважды с выводом в поток, а не в файл. Секреты уборщика непустые и различаются, сравнение по хэшу, значения не печатаются. Рабочий.envне меняется. Затем — шаг оператора из шапки. - строки
-
5.2 Bootstrap по решению 8 и дельте
object-storage:infra/s3/bootstrap.sh: шаги пользователя общие дляapiиcleaner;- политика
cleaner-objects(s3:GetObject,s3:DeleteObjectна<bucket>/*); - ожидание ключа уборщика через DELETE несуществующего ключа, распознавание нового секрета;
- проверки
applyпо спеку, строки режимаcheckсо своим проверочным объектом, уборка вcleanup; - окружение
s3-bootstrapвdocker-compose.yml—S3_CLEANER_*.
Проверка на временном проекте compose (
-pсвоё имя,--env-file— файл в scratchpad из.env.exampleсо случайными секретами; после —down, созданные volumes перечислить в отчёте):- первый запуск — «user cleaner created»;
- повтор дважды — «exists», код 0;
- новый секрет уборщика — ключ пересоздан, прежний секрет — 403
SignatureDoesNotMatch; - ключ уборщика: GET и DELETE своего объекта — 200 и 204, повторный DELETE — 204, запись, список, bucket, политика, ACL, чужой bucket — 403.
На рабочем стенде после шага оператора —
make s3_check: код 0, строки ключа уборщика есть. -
5.3 Сервис
cleanerпо решению 9 и дельтеcontainer-run:- якорь S3 делится на адрес и ключи;
DATABASE__POOL_SIZE: "1";- healthcheck выключен,
stop_grace_period: 10s; - лимиты по замеру
docker statsв простое и во время прохода.
Проверка на рабочем стенде (
make run_docker, решение 9, «Migration Plan»):docker compose ps—cleanerработает, портов нет;- журнал — «Started cleaner» с интервалом 60, grace 900, выборкой 100;
docker compose config— секреты по сервисам по дельте;docker compose stop cleaner— быстрее 10 с, код 0, «Stopped cleaner»;docker compose up -d --no-deps cleaner && docker compose stop cleanerсразу после старта — код 0 и «Stopped cleaner before startup».
-
5.4
bench/по решению 9:compose_env—S3_CLEANER_*;bench.compose.yml—cleanerописан, какs3, и не запускается;- комментарии.
Проверка — задача 8.2.
6. Тесты отказов
-
6.1
student-tests/fault_hook.pyпо таблице решения 10:- действия
attachment-ids,last-pending,object-ids(файлыoriginalизfs.tree),fail-attachments insert|ready|stall <filename>,clear-fail-attachments,kill-api,start-api; count-attachments,count-objectsубраны;- docstring.
Имя контейнера API — только
<FAULT_PROJECT>-api. Проверка: разборfs.treeна образце из пробы design (каталог<id>безoriginalне считается,idсoriginalв середине и в конце списка считаются); поведение — тесты 6.3. - действия
-
6.2
run_failures.pyиfailures.compose.ymlпо решению 10:cleanerпосле bootstrap с grace 20 с, интервалом 1 с,restart: "no";FAULT_CLEANER_GRACE_S,FAULT_CLEANER_INTERVAL_S— тестам и строкойsayв вывод команды;- журнал уборщика при падении;
- docstring.
Проверка:
make failure_checks FAULT_ARGS='-k health'— код 0, в выводе строка уборщика с grace 20 и интервалом 1, стенд удалён;make failure_checks FAULT_ARGS='-k no_such_test'— pytest не собрал тестов (код 5), команда завершается с ненулевым кодом, вывела журналы API и уборщика, стенд удалён.
-
6.3
student-tests/test_failures.pyпо таблице решения 10:- меняются
test_upload_with_object_storage_stopped(множестваidи S6),test_rejected_uploads_leave_nothing(множестваid),test_object_storage_paused(уборка послеunpause); - новые
test_metadata_insert_failure,test_interrupted_body,test_ready_failure_compensated,test_killed_between_put_and_ready,test_cleaner_survives_outages; - маркеры
specдословно по сценариям дельт, отказы хранилищ — вwith outage(...), триггеры снимаются вfinally; - помощники: множества, объекты без строки, ожидание с крайним сроком G + I + 5 с.
Проверка:
make failure_checks FAULT_ARGS='-k "attachment or object_storage or cleaner or interrupted or metadata or killed or ready_failure"';- полный
make failure_checks— код 0, сводка журнала PostgreSQL без признаков аварии, стенд удалён, у рабочего стенда прежнийStartedAt; - время прогона — в design, «Уточнения apply».
- меняются
-
6.4 Сверка покрытия:
storage-consistencyвCAPABILITIES(spec_coverage.py);- синхронизация всех дельт change в основные спеки (
/opsx:sync), как вattachments.
Проверка:
make student_testчерез LB — сверка без «no test and no exclusion» и «unknown scenario», итог называет число сценариев проверок отказов с новыми;openspec validate --specs.
7. Драйвер скилла run-mtusi-messenger
-
7.1
driver.py --port <LB> upload-consistencyпо решению 11 и раздел вSKILL.md: шаги, что проверяется, коды выхода, gotchas. Gotchas:- grace разового запуска не меньше 18 с;
- уборщик сервиса эти строки не трогает;
- на время
pauseS3 вложения стенда отвечают 503.
Проверка:
- на рабочем стенде — код 0; после команды у
attachmentsнет триггеров драйвера, его функций тоже нет (psql:\dS+ attachments,\df); - отрицательная:
--portконсольного процесса без LB — код 2 и понятное сообщение; make lintиruff format --checkдрайвера.
8. Регресс и проверка кода
- 8.1 Рабочий стенд после
make run_docker, иначеmake rolling_updateиdocker compose up -d s3-bootstrap cleaner:make test—PASS: lab4;make student_testчерез LB;make test_isolated— зелёный;make test-persistence ACTION_SCRIPT=scripts/restart.sh. Уборщик переживает рестарт PostgreSQL и S3: в его журналеwarningотказа,RestartCount0 и прежнийStartedAt, а разовыйdocker compose run --rm --no-deps cleaner --onceпосле рестарта — код 0;make test-failover ACTION_SCRIPT=scripts/stop-one.sh, между прогонамиmake replicas;make s3_check.
- 8.2 Регресс
bench/:make bench_quick,make bench_failover_quick,make bench_rollout_quick,make bench_restore_quick— код 0. Вrolloutсe1161f7применяются обе ревизии, в том числе индекс под нагрузкой, ошибок нет. Меткиquick-*в git не идут. - 8.3
make lint,make check,openspec validate upload-consistency --type change --strict,openspec validate --specs,graphify update ..
9. Документы
-
9.1 Правила по решениям:
service-layer.md— ветки ошибок загрузки и компенсация, сервис уборки и его транзакции;repo-layer.md— функции кандидатов, блокировки и удаления,delete_original;infra.md—session_scope, клиенты процесса уборщика, пул 1;docker.md— сервисcleaner, healthcheck, секреты по сервисам, пользователь уборщика в bootstrap,restart.shуборщика не трогает;settings.md—[cleaner],S3_CLEANER_*, шаг оператора;logging.md— записи уборщика и новые записиattachment_service;run-modes.md— точка входа уборщика, сигналы, консоль без уборщика;migrations.md— индексCONCURRENTLYвautocommit_blockи починка INVALID-индекса;student-tests.md— действия hook, множества вместо счётчиков, новые тесты, уборщик на стенде отказов, время прогона;balancer.md—rolling-update.shуборщика не пересоздаёт.
AGENTS.md:
- карта кода:
src/cleaner/,attachment_cleanup.py,session_scope; - команды:
driver.py upload-consistency, времяmake failure_checks; - правила лабы 4: уборщик и его права S3;
- таблица важных файлов.
PLAN.md,### upload-consistency— «Решения» из apply. Проверка:grep -rn "count-objects\|count-attachments" AGENTS.md .claude student-testsпуст;make lint.
10. Коммит, evidence, отчёт
-
10.1 Финальная проверка задач 8.1 и 6.3 на текущем коде. Затем показать изменения, предложить сообщение коммита и после подтверждения закоммитить (основная сессия).
-
10.2 Evidence с закоммиченного кода по решению 11. Без токенов, паролей и секретов S3, в каждом файле команда, дата, commit и стенд:
evidence/attachments/consistency.md;evidence/attachments/cleaner-process.md;evidence/s3/cleaner-key.md;evidence/migrations/pending-index.md;evidence/tests/failure-checks.md.
Проверка:
grepзначений секретов из.envпоevidence/пуст (значения не печатаются);make student_testзелёный. Коммит — после подтверждения. -
10.3
REPORT.mdпо решению 11:- раздел «Согласованность БД и S3»;
- ответ на вопрос защиты «PUT прошёл, COMMIT нет»;
- строка уборщика в таблице сервисов, сумма лимитов и расчёт соединений;
- строки уровня «4» вместо TODO
upload-consistency; - ограничения;
- шаг оператора
.env.
Строку этапа 3 в
PLAN.md— по факту. Проверка: у каждой новой строки таблицы доказательств есть команда, наблюдение и файл;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. Новый или изменённый сценарий правится и в дельте, и в основном спеке дословно.
-
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. - уборщик:
-
11.2 W2, «исход COMMIT неизвестен»: режим hook
fail-attachments commit <filename>(отложенный триггер ограничения, 08006), сценарий «Исход фиксации неизвестен» (attachments), тестtest_ready_commit_outcome_unknown: 503, строкаpending, объект есть сразу после ответа; через G + I + 5 с ни строки, ни объекта, объектов без строки нет. Проверка: тест красный на временной регрессии «компенсация на любой сбой» (правка откатывается), зелёный на коде. -
11.3 W3, «строку убрал уборщик до
ready»: режим hookfail-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/пуст. -
11.5 S1:
.claude/rules/docker.md, раздел «Уборщик» —entrypoint, а неcommand. Проверка: текст совпадает сdocker-compose.yml. -
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; строка этапа 3PLAN.md.