Files
mtusi2026lab4/openspec/changes/upload-consistency/tasks.md
T
ricoromaandClaude Opus 5.5 5889ca2ad7 fix: delete the object and the row in one locked cleanup transaction
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>
2026-10-21 22:08:29 +03:00

30 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.

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.
  • 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), docstring attachment_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 и раздела 7 evidence/attachments/cleaner-process.md с нового commit; числа в REPORT.md и PLAN.md. Проверка: grep секретов по evidence/ (значения не печатаются), make lint, make check, openspec validate upload-consistency --type change --strict.