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>
43 KiB
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.lockaio-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_*, шапка с сопоставлением имён skeletonBROKER_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 статуса и новый CHECKerror_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, закрытие в lifespansrc/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(jsonschemadev-группы); лишнее поле, чужаяschema_version,attempt0, неверный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,RestartCount0;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» со всеми значениями, затем запись о готовом вложении;
filenamesmoke в журнале нет; 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после откатов совпадает с кодом до них. - ack до фиксации результата →
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.