Files
mtusi2026lab5/openspec/changes/async-attachments/tasks.md
T
ricoromaandClaude Opus 5.5 ff1a83b6ff feat: process attachments asynchronously with RabbitMQ and a worker
Upload answers 202 after staging, a queued job in PostgreSQL and a broker
confirm; a separate worker publishes the original and a thumbnail with
bounded retries. Adds the job and variant tables, the broker service, the
worker S3 user, cleanup and reconcile support for staging and variants,
the failure stand with broker and worker, bench and driver updates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 06:48:20 +03:00

43 KiB
Raw Blame History

Tasks

Как строить — design.md (дальше «решение N»), что должно получиться — дельты в specs/. Перед первым файлом слоя прочитать его правило: service-layer.md, repo-layer.md, dto.md, infra.md, api-layer.md, api-contract.md, migrations.md, logging.md, settings.md, run-modes.md, docker.md, balancer.md, student-tests.md, bench.md.

Граница коммита. Группы 1–14 — код, тесты, инструменты и правила: проверяются на рабочем дереве, агент apply не коммитит и в evidence/ не пишет. Группа 15 — снятие evidence и REPORT.md: её запускает основная сессия после коммита групп 1–14, на закоммиченном коде (bench.md, «Измеренное состояние — commit»).

Шага оператора нет. make env_setup сам дописывает секреты брокера и ключи worker в существующий .env, значения не печатает. Руками .env не читать и не править.

Ожидаемо красное, остальное разбирается по AGENTS.md:

  • make test и сценарии вложений — до конца группы 9: API ещё не на 202 или worker нет;
  • между задачами 10.1 и 10.9 — сверка покрытия: «marker points to unknown scenario»; sync раньше тестов дал бы обратное, «no test and no exclusion»;
  • test_exclusion_evidence_exists — до группы 15, а по файлам старых исключений — до последнего шага всего прогона (QUESTIONS.md, «Перенос из лабы 4»). В группах 1–14 это не регрессия, но падать он должен только по missing_evidence.

Решения по ходу работы — design, «Уточнения apply»; вопросы и решения без пользователя — QUESTIONS.md, ## async-attachments; дефект, найденный попутно, — KNOWN_ISSUES.md.

1. Зависимости, настройки, общие типы

  • 1.1 Зависимости: aio-pika>=10.2.1,<11 в основной группе, pillow>=13,<14 из dev-группы в основную, uv lock.

    Проверка: uv lock --check; в uv.lock aio-pika 10.2.1, aiormq 7.2.4, pamqp 4.0.1, Pillow 13.0.0; uv tree --no-dev содержит обе.

  • 1.2 Настройки по решению 13 и дельте service-configuration:

    • классы Broker и Worker в src/config/settings.py, пароль — SecretStr, как у [s3];
    • graceful_shutdown_seconds не больше 9, сроки больше нуля, concurrency и max_attempts не меньше 1;
    • строки с комментариями единиц в config_example.toml.

    Проверка: uv run python -c "from src.config import settings; print(settings.worker)" — значения по умолчанию; BROKER__PUBLISH_TIMEOUT_SECONDS=0 и =abc, WORKER__CONCURRENCY=0, WORKER__MAX_ATTEMPTS=abc, WORKER__GRACEFUL_SHUTDOWN_SECONDS=10 — ошибка проверки настроек называет поле.

  • 1.3 Секреты и порты по решению 13:

    • .env.example: блок брокера (RABBITMQ_DEFAULT_USER, RABBITMQ_DEFAULT_PASS пустой, RABBITMQ_HOST, RABBITMQ_PORT, RABBITMQ_OUT_PORT, мосты BROKER__*), ключи S3_WORKER_*, шапка с сопоставлением имён skeleton BROKER_URL_FILE, WORKER_CONCURRENCY, JOB_MAX_ATTEMPTS, JOB_TIMEOUT_SECONDS, STAGING_RETENTION_SECONDS;
    • Makefile: ENV_SECRETS, ENV_FILLED.

    Проверка: подстановки рецепта env_setup дважды в поток, а не в файл: новые секреты непустые и различаются, сравнение по хэшу, значения не печатаются. make env_setup на рабочем каталоге печатает только имена дописанных переменных, повтор ничего не дописывает.

  • 1.4 Общие типы:

    • src/schemas/enums/attachment.py: AttachmentStatus — ещё queued, processing, failed; новые AttachmentJobState, AttachmentVariantName, AttachmentErrorCode, AttachmentJobReason;
    • src/utils/constants.py: ATTACHMENT_PIPELINE_VERSION, ATTACHMENT_JOB_TYPE, ATTACHMENT_JOB_SCHEMA_VERSION, ATTACHMENT_STAGING_PREFIX, THUMBNAIL_MAX_SIDE, THUMBNAIL_JPEG_QUALITY, имя очереди;
    • src/core/exceptions: AttachmentNotReady и AttachmentFailed (409 в DOMAIN_ERRORS), BrokerUnavailable(ServiceUnavailable).

    Проверка: make lint; uv run python -c "import src.api.errors".

2. Схема

  • 2.1 Модели по решению 1: новые колонки и CHECK Attachment, AttachmentJob, AttachmentVariant в src/infra/db/models/attachment.py.

    Проверка: make lint; совпадение со схемой — задача 2.2.

  • 2.2 Ревизия поверх 5c3e1f0a9b7d руками по решению 1 и migrations.md: первой строкой SET LOCAL lock_timeout = '2s', колонки, замена CHECK статуса и новый CHECK error_code с NOT VALID, две таблицы, downgrade.

    Проверка на временной базе (createdb в контейнере postgres, DATABASE__NAME в окружении, после — DROP DATABASE):

    • upgrade с нуля, uv run alembic check пуст, повтор ничего не меняет, downgrade -1, upgrade;
    • на базе со строками pending и ready: status прежний, pg_constraint.convalidated у обоих CHECK — false;
    • второе задание той же версии, второй вариант того же имени, error_code у не failed, failed без кода — нарушение ограничения; удаление вложения с заданием — нарушение внешнего ключа;
    • транзакция держит attachments дольше 2 с: миграция падает без изменений, повтор проходит.

3. DTO и repo

  • 3.1 DTO по dto.md: AttachmentFullDTO — staging_key, error_code, variants кортежем по умолчанию; AttachmentInListDTO.staging_key; AttachmentJobDTO, AttachmentVariantDTO; __init__.py.

    Проверка: make lint.

  • 3.2 src/core/repos/attachment.py по решениям 1–3 и repo-layer.md, одно выражение на функцию, updated_at через greatest:

    • _ATTACHMENT_COLUMNS, _STALE_COLUMNS, вставка со staging_key;
    • mark_ready заменяется на mark_queued с теми же условиями (pending, updated_at = created_at);
    • новые: возврат в pending, перевод в processing и обратно в queued, условная фиксация ready и failed с кодом.

    Проверка: make lint; поведение — группы 6–8 и 10.

  • 3.3 src/core/repos/attachment_job.py по решениям 1, 3, 7: вставка, чтение с FOR UPDATE, чтение по вложению, начало попытки, возврат в queued с условием своей попытки, завершение, отметка published_at, условное удаление (state = 'queued' AND attempt = 0).

    Проверка: make lint; поведение — группы 6–7 и 10.

  • 3.4 src/core/repos/attachment_variant.py: вставка ON CONFLICT DO NOTHING по ключу эффекта, варианты вложения, один вариант по имени.

    Проверка: make lint; поведение — группы 6–7 и 10.

  • 3.5 src/core/repos/attachment_object.py по решению 1: staging_key, variant_key, parse_variant_key; запись и чтение остаются по ключу.

    Проверка: разовый вызов parse_variant_key: свой id и v1-thumbnail — id, верхний регистр, версия 0, неизвестное имя, original, чужой префикс — None; make lint.

4. Брокер: сервис и клиент

  • 4.1 Сервис rabbitmq по решению 4 и docker.md:

    • docker-compose.yml: образ с тегом и digest из решения 4, hostname, volume, порт, алиас, healthcheck, лимиты, stop_grace_period, якорь x-broker-env;
    • infra/rabbitmq/rabbitmq.conf, монтирование read-only длинной записью;
    • цели start_broker, stop_broker.

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

    • docker buildx imagetools inspect rabbitmq:4.3.7 — тот же digest;
    • make start_broker — healthy; rabbitmqctl -q status --formatter json — предел памяти 400 МиБ; docker port — только AMQP на 127.0.0.1;
    • docker compose stop rabbitmq — код 0 раньше срока;
    • docker compose up -d --force-recreate rabbitmq — healthy, имя узла rabbit@rabbitmq прежнее; очередь с сообщениями после пересоздания — тест test_broker_recreated.
  • 4.2 Клиент по решению 5: src/infra/broker/client.py (JobPublisher, JobConsumer, имя очереди из namespace, сброс соединения после любой ошибки), aio_pika и aiormq на WARNING в src/infra/logger.py, записи журнала по решению 18.

    Проверка — разовый скрипт в scratchpad против брокера стенда:

    • публикация с подтверждением, очередь durable, сообщение persistent;
    • нет маршрута при удалённой очереди и docker compose stop rabbitmq — BrokerUnavailable быстрее срока; docker pause — не позже срока с запасом;
    • после возврата брокера следующая публикация проходит на том же объекте издателя;
    • потребитель получает сообщение, prefetch_count соблюдён, обрыв завершает его итератор;
    • значения пароля в выводе нет (сравнение с .env без печати).
  • 4.3 Глобал API по решению 5: src/infra/broker/instance.py, src/api/dependencies.py, закрытие в lifespan src/main.py, поля брокера в «Started API».

    Проверка: make lint; процесс API стартует и отвечает /health/ready при остановленном брокере; в «Started API» адрес, очередь и срок, пароля нет.

5. Thumbnail

  • 5.1 src/utils/thumbnail.py по решению 8.

    Проверка — разовый скрипт в scratchpad с генераторами student-tests/images.py:

    • 320 × 200 → 256 × 160, 100 × 50 и 256 × 256 без изменений, 1000 × 601 → 256 × 153, 601 × 1000 → 153 × 256, 5000 × 10 → 256 × 1, 10 × 5000 → 1 × 256;
    • orientation 1–8: размеры и пиксели как у ImageOps.exif_transpose;
    • alpha, палитра с tRNS, LA — белый на месте прозрачности;
    • все png_variants() и jpeg_variants() — настоящий JPEG; точность SOF 12 — InvalidImage;
    • пик RSS PNG RGBA 8000 × 5000 в контейнере образа с лимитом 1 ГБ — не больше ~350 МиБ.

    grep -rn "PIL" src — только этот модуль; его импортирует только сервис обработки.

6. API

  • 6.1 AttachmentService по решению 3: издатель в конструкторе и зависимости; _store пишет в staging; _mark_ready → перевод в queued с заданием и той же компенсацией; публикация, отметка published_at, транзакция отмены; места загрузки держатся до ответа; записи журнала по решению 18, filename в них нет.

    Проверка: make lint; один PNG против консольного API и брокера стенда — 202, строка queued, объект только в staging, одно сообщение; сбои — тесты группы 10.

  • 6.2 Чтение по решению 9: pending — 404, остальные — 200, варианты только у ready; open_content(variant=…): статус не ready — AttachmentNotReady без обращения к S3, нет варианта — 404, нет объекта варианта или другой размер — 500 с записью error; ветки оригинала и lost_at прежние.

    Проверка: make lint; поведение — тесты группы 10.

  • 6.3 MessageService по решению 9: неизвестное, чужое и pending — 404 до ключа; failed — после захвата ключа: новый ключ — откат и AttachmentFailed, занятый — прежняя ветка повтора.

    Проверка: make lint; поведение — тесты группы 10, в том числе «Повтор после failed вложения».

  • 6.4 HTTP по решению 9: status_code=202, variant как Literal четырёх значений, модель Attachment с status, variants, error_code, модель варианта, DOMAIN_ERRORS, версия 1.5.0 в create_app.

    Проверка: /openapi.json запущенного API против contracts/openapi.json: поля и обязательность Attachment и Variant, перечисления, код успеха загрузки, info.version.

7. Worker

  • 7.1 Сообщение задания: pydantic-модель src/schemas/jobs/attachment.py (решение 7), сборка тела из строки задания и номера попытки. Правило dto.md дополняется в задаче 13.1.

    Проверка: тело по contracts/jobs.schema.json (jsonschema dev-группы); лишнее поле, чужая schema_version, attempt 0, неверный traceparent — ошибка разбора; traceparent и tracestate по схеме проходят.

  • 7.2 AttachmentProcessingService в src/core/services/attachment_processing.py по решениям 2 и 7: разбор, таблица claim, обработка под сроком, фиксация ready с вариантом одной транзакцией, временные и постоянные ошибки, недоступный PostgreSQL, исход ACK или REQUEUE; порядок блокировок — задание, затем вложение; журнал по дельте service-logging.

    Проверка: make lint; поведение — тесты группы 10.

  • 7.3 Процесс src/worker/ по решению 6: __main__.py (early_stop.install("worker"), «Invalid worker settings», код 2, os._exit), main.py (сигналы, свои engine, S3 и клиенты брокера, цикл переподключения, ограниченная конкуренция, контекст request_id, остановка в срок, «Started worker» и «Stopped worker»).

    Проверка без стенда: WORKER__CONCURRENCY=0 uv run python -m src.worker — код 2, запись называет поле без значений; make lint. На стенде — задача 9.6.

8. Уборщик и сверка

  • 8.1 Уборщик по решению 11: staging_key в выборках; remove_stale_pending удаляет staging_key or object_key, запись журнала называет удалённый ключ.

    Проверка: make lint; разовый python -m src.cleaner --once на стенде после 9.6 — код 0; поведение — тесты группы 10. Профиль reconcile со строками прежнего вида — задача 11.2.

  • 8.2 Сверка по решению 11: разбор ключа варианта в _list_objects, id вариантов в выборке страницы, ветка варианта в _classify_object (строка есть — пропуск, нет — объект без метаданных, свежий — свежий); находка зависшей загрузки называет ключ staging; is_own_key по-прежнему смотрит object_key.

    Проверка: make lint; на стенде обе стратегии без --apply не называют объекты вариантов; поведение — тесты группы 10.

9. Стенд

  • 9.1 docker-compose.yml по решениям 6 и 10: сервис worker, x-broker-env и depends_on брокера у api, ключи S3_WORKER_* у s3-bootstrap.

    Проверка: docker compose --env-file .env config --quiet; docker compose config — секреты по сервисам по дельте container-run: пароль брокера только у rabbitmq, api, worker, ключи worker только у s3-bootstrap и worker, у worker нет пароля Valkey и ключей API и уборщика.

  • 9.2 infra/s3/bootstrap.sh по решению 12: apply_user worker worker-objects, политика, ожидание ключа, проверки apply и check, отказ на удаление и список; driver.py s3-check — строки ключа worker.

    Проверка на временном проекте compose (-p своё имя, --env-file — файл в scratchpad, порты свободные; без down -v: созданные volumes перечислить в отчёте и оставить основной сессии): первый запуск — «user worker created»; повтор дважды — «exists», код 0; новый секрет — ключ пересоздан, прежний отклонён; все запреты сценария «Запрещённые операции worker» — 403.

  • 9.3 Makefile: run_worker (рецепт с @, ключи worker в окружение процесса), run_dev и test_isolated зависят от start_broker, текст wipe_data называет volume брокера, комментарии стенда.

    Проверка: make run_worker не печатает значения ключей; make run_dev и make run_worker — загрузка становится ready, «Started worker» называет адрес 127.0.0.1:$RABBITMQ_OUT_PORT.

  • 9.4 scripts/restart.sh по решению 14 (брокер в restart и up --wait --no-recreate), шапка; комментарии scripts/rolling-update.sh и infra/haproxy/haproxy.cfg — 29 с и 76 с.

    Проверка: scripts/restart.sh на стенде — код 0 не дольше 90 с, у брокера и реплик те же ID и новый StartedAt, у worker и уборщика прежний StartedAt, RestartCount 0; haproxy -c закреплённым образом.

  • 9.5 CI по решению 14: .github/ci/compose.yml (rabbitmq, worker), .github/ci/stand-env.sh (CI_RABBITMQ_CONF); шаги workflow не меняются.

    Проверка: COMPOSE_FILE=docker-compose.yml:.github/ci/compose.yml, CI_IMAGE_TAG и . .github/ci/stand-env.sh, docker compose config --quiet — без ошибок; в docker compose config у rabbitmq и worker нет ports и bind mount, у rabbitmq есть volume данных, а образ worker — тег прогона.

  • 9.6 Рабочий стенд на рабочем дереве: make run_docker.

    Проверка:

    • docker compose ps — две реплики, уборщик, worker, брокер и S3 в рабочем состоянии, bootstrap с кодом 0;
    • make test — PASS: lab5;
    • журнал worker: «Started worker» со всеми значениями, затем запись о готовом вложении; filename smoke в журнале нет;
    • docker compose stop worker — быстрее 10 с, код 0, «Stopped worker»; docker compose up -d --no-deps worker и сразу stop — код 0 и «Stopped worker before startup»;
    • /proc/1/cmdline контейнера worker — python -m src.worker, проверки здоровья нет; в /proc/1/maps реплики API нет _imaging;
    • make s3_check — код 0, строки ключа worker на месте.

10. Тесты

  • 10.1 Клиент и генераторы по решению 15: api_client.py (upload — 202 и снимок queued, wait_attachment, upload_ready, скачивание варианта), contract.py (код 202, схема Variant, assert_content для варианта), images.py (JPEG с точностью 12 и с EXIF orientation, половины цветов, PNG с прозрачной половиной и палитрой с tRNS, большой PNG RGBA).

    Проверка: make lint; wait_attachment при остановленном worker падает и называет queued (сценарий «Worker не работает»).

  • 10.2 Прежние сценарии вложений во всех модулях обычного набора (test_attachments.py, test_messages.py, test_idempotency.py, test_rubric.py, test_data_storage.py, test_api_conventions.py, test_load_balancing.py и другие, где есть загрузка): 202 и ожидание ready там, где нужны байты или итог; метаданные сравниваются по полям оригинала и отдельно по полям состояния; проверки не ослабляются и не пропускаются (спек student-tests, «Готовность вложения в тестах»).

    Проверка: make student_test через LB — прежние сценарии зелёные, красное только из шапки.

  • 10.3 Новый модуль test_attachment_processing.py и новые тесты обычного набора по таблице «Покрытие сценариев» design: test_attachment_becomes_ready, test_thumbnail_*, test_download_thumbnail, test_missing_variant, test_variant_outsider, test_message_with_failed_attachment, test_accepted_attachment_visible_on_other_replica; маркеры spec дословно по сценариям дельт.

    Проверка: uv run pytest student-tests/test_attachment_processing.py с BASE_URL стенда; thumbnail скачан и его настоящие размеры, sha256 и size_bytes сверены с метаданными варианта.

  • 10.4 Hook student-tests/fault_hook.py по решению 15 и дельте student-tests: действия брокера и worker, worker-state, queue-state, peek-job, publish-job, delete-queue, job, staging-ids, variant-object-count; put-object и delete-object под префиксами вложений и staging; режимы fail-attachments на queued и → ready; docstring. Ключи S3 и пароль брокера hook не получает и не печатает.

    Проверка: разбор fs.tree на образце (original и v1-thumbnail в одном каталоге, staging отдельно); hook отказывается работать с проектом рабочего стенда; поведение действий — тесты 10.6 и 10.7.

  • 10.5 Стенд отказов по решению 15: failures.compose.yml (rabbitmq без порта, worker с короткими сроками, restart: "no"), run_failures.py (брокер в up --wait, worker после bootstrap, FAULT_WORKER_*, журнал worker при падении, строка start worker, уборка), docstring.

    Проверка: make failure_checks FAULT_ARGS='-k health' — код 0, строка worker в выводе, стенд и volumes удалены; -k no_such_test — ненулевой код, журналы API, уборщика и worker напечатаны, стенд удалён.

  • 10.6 Прежние проверки отказов test_failures.py по решению 15 и дельтам attachments и storage-consistency:

    • upload_ready и множества id там, где нужен готовый объект;
    • test_ready_failure_compensated → test_queued_failure_compensated, test_ready_commit_outcome_unknown → test_queued_commit_outcome_unknown; test_killed_between_put_and_ready, test_upload_outlives_grace, test_cleaner_failure_after_object_delete — на queued и staging-ids;
    • тесты сверки: зависшая загрузка — объект в staging, готовые вложения — с объектами вариантов.

    Проверка: make failure_checks FAULT_ARGS='-k "attachment or object_storage or cleaner or reconcile or upload"' — код 0.

  • 10.7 Новые проверки отказов по таблице «Покрытие сценариев» design: сценарии attachment-processing, message-broker, messages, idempotency, health, attachments, storage-consistency, а также test_worker_stop_during_processing (спек graceful-shutdown в докстринге). Отказы — в with outage(...), worker запускается в finally, триггеры снимаются в finally. Сообщение проверяется по contracts/jobs.schema.json.

    Проверка: полный make failure_checks — код 0, сводка журнала PostgreSQL без признаков аварии, стенд удалён, у контейнеров рабочего стенда прежний StartedAt; время прогона — в design, «Уточнения apply».

  • 10.8 make test_isolated по решению 15: run_isolated.py — контейнер <проект>-test-worker с той же подменой базы, журналы обоих контейнеров, удаление очереди в начале и в конце, KEEP_TEST_DB печатает очередь; проверка имени очереди — как у префикса, иначе код 2.

    Проверка: make test_isolated при работающем стенде — код 0; после него нет контейнеров, базы, объектов и очереди временной базы, а сообщения и счётчики рабочей очереди и StartedAt рабочего стенда прежние; прерывание Ctrl+C — уборка выполнена; KEEP_TEST_DB=1 — остаётся и печатается.

  • 10.9 Сверка покрытия:

    • attachment-processing и message-broker в CAPABILITIES, записи EXCLUDED с причинами и способом проверки по design (message-broker «Сервис брокера запущен», «Предел памяти брокера», «Остановка брокера», «Очереди разных баз разделены», data-storage «Ограничения обработки в схеме»);
    • sync всех 18 дельт в основные спеки (/opsx:sync): сверка читает только openspec/specs/.

    Проверка: openspec validate --specs; make student_test — сверка без «no test and no exclusion» и «unknown scenario», красное только missing_evidence; итог называет число сценариев проверок отказов с новыми.

  • 10.10 Тесты ловят нарушение: временные регрессии, каждая откатывается и не попадает в рабочее дерево:

    • ack до фиксации результата → test_worker_killed_during_processing красный;
    • публикация без подтверждения → test_upload_with_broker_stopped или test_upload_with_broker_paused красный;
    • очередь не durable → test_broker_restart_keeps_job красный;
    • Image.thumbnail вместо своего расчёта → test_thumbnail_rounding красный;
    • failed до захвата ключа → test_replay_after_attachment_failed красный;
    • сверка без ветки варианта → test_reconcile_variant_objects красный.

    Проверка: итог по каждой регрессии — в design, «Уточнения apply»; git diff после откатов совпадает с кодом до них.

11. bench/

  • 11.1 Стенд по решению 16: bench.compose.yml (rabbitmq, worker, лимиты), bench.env, compose_env (пароль брокера, ключи worker), поля Profile, SECRET_ENV_MARKS покрывает новые имена, старт брокера в профиле загрузок, новый volume брокера на прогон, остатки и уборка.

    Проверка: uv run python bench/uploads.py --selftest; make bench_quick — код 0, брокер и worker не запущены, stand.app_env без секретов.

  • 11.2 Профиль загрузок по решению 16: k6/uploads.js, uploads.py (s201 — код успеха варианта, столбец success_code в конце, раздел паспорта), run.py, тексты сводки.

    Проверка: make bench_uploads_quick — код 0, успешные загрузки — 202, пик памяти реплики и 429 — в тех же границах, что у прежних сценариев спека; make bench_reconcile_quick — код 0, зависшие строки прежнего вида убраны: сверка моделей сошлась. Метки quick-* в git не идут.

12. Драйвер скилла run-mtusi-messenger

  • 12.1 Прежние команды по решению 17: start поднимает брокер и worker, upload, download, flow, attachment-failover, attachment-storage, upload-consistency, reconcile-*, s3-idle — 202 и ожидание ready; заглушка реплики lb-upload-timeouts — 202; attachment-storage — ещё пробы ограничений обработки в откатываемой транзакции.

    Проверка: каждая из этих команд на рабочем стенде — код 0; driver.py lb-upload-timeouts — пять случаев с 202.

  • 12.2 Новые команды по решению 17: defense-scenario, broker-check [--require-test-queue], worker-process; раздел в SKILL.md: шаги, что проверяется, коды выхода, gotchas.

    Проверка:

    • defense-scenario на рабочем стенде — код 0, вывод с шагами, кодами, id и StartedAt до и после, токенов и секретов нет;
    • прерывание сигналом посреди сценария — worker запущен, код ненулевой;
    • broker-check, worker-process — код 0; отрицательная: broker-check --require-test-queue без прогона на временной базе — код 1;
    • ruff format --check драйвера.

13. Правила и карта кода

  • 13.1 Правила по решениям:

    • новое .claude/rules/worker.md с paths (src/worker/**, сервис обработки, thumbnail.py), строка в AGENTS.md, «Где лежат инструкции»;
    • api-contract.md — 202, 409, 404, attachment_ids; api-layer.md — параметр variant;
    • service-layer.md, repo-layer.md, dto.md (модель сообщения), infra.md (broker/), migrations.md, logging.md, settings.md, run-modes.md, docker.md, balancer.md (29 с и 76 с, порядок обновления), student-tests.md (hook, модуль, ожидание ready, время прогона), bench.md.

    Проверка: grep -rn "201 Attachment\|mark_ready\|Pillow — только dev" .claude AGENTS.md — только верные упоминания; make lint.

  • 13.2 AGENTS.md: текущий статус, правила лабы 5, таблица важных файлов и команд, карта кода (src/worker/, src/infra/broker/, сервис обработки, thumbnail.py, infra/rabbitmq/, новые модули и файлы тестов), время make failure_checks. KNOWN_ISSUES.md — разрыв COMMIT и publish до pipeline-reliability, смесь версий при замене. QUESTIONS.md — решения, принятые в apply.

    Проверка: каждый новый файл git status назван в карте кода или таблице; make lint, make check.

14. Регресс на рабочем дереве

  • 14.1 Смесь версий и откат по Migration Plan design на рабочем стенде: docker compose stop worker cleaner, make rolling_update COMMIT=cc33a03 MIGRATE=0, затем вперёд: make rolling_update, docker compose up -d --no-deps cleaner worker. Первое обновление с прежней версии под нагрузкой показывает make bench_rollout_quick (задача 14.3).

    Проверка: на прежнем образе сообщения и история — 200, загрузка — 201 ready, чтение вложения в новом статусе — 500 (названное ограничение); после возврата на текущий код lb_stats без ручных состояний, новые вложения становятся ready, вложение прежнего образа — 200, variants пуст, variant=thumbnail — 404, сверка без расхождений по нему.

  • 14.2 Рабочий стенд:

    • make test — PASS: lab5, make validate, make check;
    • make student_test через LB — красное только missing_evidence;
    • make run_dev с make run_worker и EXPECT_REPLICAS=1 make student_test — те же итоги, кроме тестов реплик;
    • make test_isolated, полный make failure_checks;
    • make test-persistence ACTION_SCRIPT=scripts/restart.sh;
    • make test-failover ACTION_SCRIPT=scripts/stop-one.sh дважды (stop, STOP_MODE=kill) с make replicas между ними;
    • make s3_check, make reconcile — код 0;
    • driver.py --port <LB> defense-scenario;
    • make wipe_data не выполнять: текст запроса и docker compose config --volumes проверить чтением.
  • 14.3 Регресс bench/: make bench_quick, make bench_failover_quick, make bench_rollout_quick (обе фазы образов, новая миграция под нагрузкой без ошибок), make bench_restore_quick, make bench_uploads_quick, make bench_reconcile_quick — код 0.

  • 14.4 Сборка из чистого дерева: команда git ls-files -z -co --exclude-standard | tar … из docker.md; в образе импорт Pillow и aio-pika, версии как в uv.lock, uv и компиляторов нет. make lint, openspec validate async-attachments --strict, openspec validate --specs.

  • 14.5 Отчёт apply для основной сессии: git status, git diff --stat, предложенное сообщение коммита, созданные пробами volumes, что осталось красным и почему. Агент останавливается здесь: коммит и группу 15 выполняет основная сессия.

15. Evidence и отчёт (после коммита, основная сессия)

Снимать на закоммиченном коде: рабочий стенд собран из HEAD (make run_docker), рабочее дерево чистое, в шапке каждого файла команда, дата, commit и стенд. Без токенов, паролей, ключей и секретов.

  • 15.1 Коммит кода групп 1–14 на ветке feat/async-attachments, стенд на этом commit: make run_docker, make replicas.

    Проверка: git status чист; docker compose ps — как в задаче 9.6; make test — PASS: lab5.

  • 15.2 Проверки и исключения сверки:

    • evidence/attachments/defense.md — driver.py --port <LB> defense-scenario;
    • evidence/broker/stand.md — driver.py --port <LB> broker-check;
    • evidence/broker/isolated.md — make test_isolated KEEP_TEST_DB=1, broker-check --require-test-queue, затем make test_isolated;
    • evidence/attachments/storage.md — driver.py --port <LB> attachment-storage, с пробами ограничений обработки;
    • evidence/attachments/failover.md — driver.py --port <LB> attachment-failover;
    • evidence/attachments/consistency.md — driver.py --port <LB> upload-consistency;
    • evidence/replicas/test-persistence.md — make test-persistence ACTION_SCRIPT=scripts/restart.sh, контейнеры и StartedAt до и после.

    Проверка: test_exclusion_evidence_exists называет только файлы старых исключений последнего шага прогона; в broker/isolated.md очередь есть после первого прогона и нет после второго.

  • 15.3 Процесс, ключи, журнал, схема:

    • evidence/worker/process.md — driver.py --port <LB> worker-process: PID 1, лимиты, остановка, неверные WORKER__*, рестарт хранилищ, значения по умолчанию и подмена окружением;
    • evidence/worker/logs.md — журнал готового и failed вложения одного request_id, запись error сообщения не по схеме, filename и секретов нет;
    • evidence/s3/worker-key.md — make s3_check и строки ключа worker;
    • evidence/migrations/async-attachments.md — проба задачи 2.2, откат на образ cc33a03 и возврат задачи 14.1;
    • evidence/uploads/lb-timeouts.md — driver.py lb-upload-timeouts.

    Проверка: grep значений секретов из .env по evidence/ пуст (значения не печатаются).

  • 15.4 Прогоны наборов на этом commit: evidence/tests/student-test-lb.md (make student_test через LB), evidence/tests/test-isolated.md, evidence/tests/failure-checks.md (полный make failure_checks, число проверок и время), метка make bench_rollout ROLLOUT_LABEL=async-attachments.

    Проверка: числа в файлах совпадают с выводом команд; красное только missing_evidence по файлам последнего шага прогона.

  • 15.5 REPORT.md:

    • архитектура стенда с брокером и worker, таблица ролей и сумма лимитов, расчёт соединений PostgreSQL;
    • запуск из чистого clone двумя способами, make run_worker;
    • сопоставление имён skeleton BROKER_URL_FILE, WORKER_CONCURRENCY, JOB_MAX_ATTEMPTS, JOB_TIMEOUT_SECONDS, STAGING_RETENTION_SECONDS;
    • таблица критериев уровня 3 с командой, наблюдением и файлом;
    • критичные и некритичные зависимости /health/ready с причинами, поведение при отказе брокера;
    • разрыв COMMIT и publish и окна отказа (решение 3), что закрывает pipeline-reliability;
    • ограничения из спеков: зависший worker и срок подтверждения брокера, постоянная пауза повтора, staging после ready и у failed, staging и конечный префикс на одном сервере S3, объект staging при заморозке API, смесь версий при замене и новые статусы, прерванное остановкой задание, сверка не проверяет объекты вариантов и staging, искажения данных скана JPEG, цепочка LB 76 с с формулой;
    • ответы на вопросы защиты README.md, порядок сценария защиты и ссылка на evidence/attachments/defense.md;
    • вопросы преподавателю из QUESTIONS.md, ## async-attachments, в разделе «Открытые вопросы преподавателю».

    Проверка: у каждой новой строки таблицы доказательств есть команда, наблюдение и файл; make lint, make check, openspec validate async-attachments --strict.

  • 15.6 Коммит evidence и REPORT.md основной сессией. Проверка: git status чист; git log -2 — commit кода назван в шапках файлов evidence.