Files
mtusi2026lab4/openspec/changes/upload-consistency/tasks.md
T
ricoromaandClaude Opus 5.5 87c48b940b 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>
2026-10-21 21:27:47 +03:00

404 lines
26 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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. Настройки, общий контекст сессии, ранний обработчик
- [x] 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`.
- [x] 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, итоги прежних тестов те же.
- [x] 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. Схема: частичный индекс
- [x] 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 и сервисы
- [x] 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.
- [x] 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.
- [x] 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. Процесс уборщика
- [x] 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».
Проверка без стенда:
- `CLEANER__PENDING_GRACE_SECONDS=17 uv run python -m src.cleaner
--once` — код 2, ошибка называет grace, оба срока и границу 17 с, к
БД и S3 нет ни одного обращения;
- `CLEANER__INTERVAL_SECONDS=abc` — ошибка проверки настроек;
- `make lint`.
## 5. Стенд
- [x] 5.1 Секреты уборщика по решению 8:
- строки `S3_CLEANER_ACCESS_KEY`, `S3_CLEANER_SECRET_KEY` с
комментарием в `.env.example`;
- `ENV_SECRETS` и замены в `make env_setup`;
- шапка шаблона — «шесть секретов S3».
Проверка: подстановки рецепта `env_setup` дважды с выводом в поток, а
не в файл. Секреты уборщика непустые и различаются, сравнение по хэшу,
значения не печатаются. Рабочий `.env` не меняется. Затем — шаг
оператора из шапки.
- [x] 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,
строки ключа уборщика есть.
- [x] 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».
- [x] 5.4 `bench/` по решению 9:
- `compose_env` — `S3_CLEANER_*`;
- `bench.compose.yml` — `cleaner` описан, как `s3`, и не запускается;
- комментарии.
Проверка — задача 8.2.
## 6. Тесты отказов
- [x] 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.
- [x] 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 и уборщика, стенд удалён.
- [x] 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».
- [x] 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`
- [x] 7.1 `driver.py --port <LB> upload-consistency` по решению 11 и
раздел в `SKILL.md`: шаги, что проверяется, коды выхода, gotchas.
Gotchas:
- grace разового запуска не меньше 18 с;
- уборщик сервиса эти строки не трогает;
- на время `pause` S3 вложения стенда отвечают 503.
Проверка:
- на рабочем стенде — код 0; после команды у `attachments` нет
триггеров драйвера, его функций тоже нет (psql: `\dS+ attachments`,
`\df`);
- отрицательная: `--port` консольного процесса без LB — код 2 и
понятное сообщение;
- `make lint` и `ruff format --check` драйвера.
## 8. Регресс и проверка кода
- [x] 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` отказа,
`RestartCount` 0 и прежний `StartedAt`, а разовый `docker compose run
--rm --no-deps cleaner --once` после рестарта — код 0;
- `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`, между
прогонами `make replicas`;
- `make s3_check`.
- [x] 8.2 Регресс `bench/`: `make bench_quick`, `make bench_failover_quick`,
`make bench_rollout_quick`, `make bench_restore_quick` — код 0. В
`rollout` с `e1161f7` применяются обе ревизии, в том числе индекс под
нагрузкой, ошибок нет. Метки `quick-*` в git не идут.
- [x] 8.3 `make lint`, `make check`, `openspec validate upload-consistency
--type change --strict`, `openspec validate --specs`, `graphify update
.`.
## 9. Документы
- [x] 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, отчёт
- [x] 10.1 Финальная проверка задач 8.1 и 6.3 на текущем коде. Затем
показать изменения, предложить сообщение коммита и после подтверждения
закоммитить (основная сессия).
- [x] 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` зелёный. Коммит — после
подтверждения.
- [x] 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. Новый или
изменённый сценарий правится и в дельте, и в основном спеке дословно.
- [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`.