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>
30 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.
12. Замечания повторной проверки
Повторный verify 2026-10-21 (HEAD 6551839): 0 CRITICAL, 1 WARNING, 2
SUGGESTION; решения основной сессии — design, «Уточнения apply», п. 21.
Изменённый текст требования или сценария правится и в дельте, и в
основном спеке дословно.
-
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.
- проба блокировок на одноразовом PostgreSQL (по образцу
-
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/— только верные упоминания. -
12.3 S1: «текущая строка доводится» и «транзакция строки откатывается» — по новой схеме:
REPORT.md, design (решения 2 и 5), docstringattachment_cleanup.py, комментарийsrc/cleaner/main.py. Проверка:grepэтих формулировок пуст. -
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и раздела 7evidence/attachments/cleaner-process.mdс нового commit; числа вREPORT.mdиPLAN.md. Проверка:grepсекретов поevidence/(значения не печатаются),make lint,make check,openspec validate upload-consistency --type change --strict.