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

26 KiB
Raw Blame History

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.

  • 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».

    Проверка без стенда:

    • 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 с;
    • уборщик сервиса эти строки не трогает;
    • на время pause S3 вложения стенда отвечают 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 отказа, 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.
  • 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»: режим 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/ пуст.

  • 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; строка этапа 3 PLAN.md.