10 KiB
Proposal
Why
Лаба 5, уровень «3» (README.md, COURSE.md, переход 4 → 5): приём файла и
тяжёлая обработка разделяются. Сейчас POST …/attachments отвечает 201 ready после записи оригинала в конечный ключ S3, обработки изображений и
брокера в стенде нет, публичный smoke лабы 5 падает уже на коде ответа. Это
первое из трёх изменений пути к оценке 5: async-attachments (3), затем
pipeline-reliability (4), track1-queue-overload (5).
What Changes
- BREAKING (объявленный переход контракта): загрузка отвечает
202 Attachmentсо снимкомstatus=queued, а не201 ready. Ответ 202 — только после оригинала в устойчивом staging (приватный префикс S3), фиксации вложения вместе с заданием в PostgreSQL и подтверждения брокера. Брокер недоступен — 503, задания не остаётся, текст и чтение работают. - Состояния в API:
queued,processing,ready,failed. Внутреннийpendingнаружу не виден. Скачивание не готового вложения — 409, отсутствующий вариант готового — 404. В сообщение можно положитьqueuedиprocessing,failed— 409; повтор уже отправленного сообщения с тем же ключом — по-прежнему 201. - Брокер: RabbitMQ 4 с volume в общем стенде, образ закреплён тегом и digest,
durable-очередь на каждое имя базы, persistent-сообщения, publisher confirms.
В сообщении только ID и служебные поля по
contracts/jobs.schema.json. - Worker: отдельная точка входа и сервис compose на образе API, свой пользователь S3 (чтение и запись объектов, без удаления и списка), ограниченная конкуренция, лимиты контейнера, остановка по SIGTERM в срок. Берёт метаданные только из БД, проверяет размер и SHA-256 staging, публикует оригинал в конечный префикс и создаёт thumbnail 256×256 JPEG (EXIF orientation, alpha на белый, округление вниз, минимум 1 px). Ack — после устойчивого эффекта.
- Повторы: ограниченный retry (
[worker] max_attempts, 5) с фиксированной паузой, финальныйfailedс безопаснымerror_code; постоянные ошибки — сразу. Повтор job не создаёт второго набора вариантов: ключ эффекта(attachment_id, pipeline_version, variant). Повторная доставка готовой работы — no-op с ack. - Схема только расширяется: таблицы
attachment_jobsиattachment_variants, колонкиattachments.staging_keyиerror_code, более широкий CHECK статуса. Колонкиpublished_at,next_attempt_at,lease_expires_atи значения вариантовcropиoptimizedесть сразу: следующее изменение добавляет механизмы без переделки контракта данных. - Существующие механизмы: уборщик по-прежнему убирает только
pending, но по ключу staging; сверка не видит staging, не трогает работу в обработке и не помечает её потерянной, а объекты вариантов считает своими. - Демонстрация защиты автоматизирована: проверкой отказа и командой драйвера с
записью в
evidence/. - Инфраструктура и инструменты:
docker-compose.yml,infra/rabbitmq/,scripts/restart.sh, стенд отказов,make test_isolated,bench/, CI,make env_setup,.env.exampleс сопоставлением имён skeleton, драйвер скилла.
Не входит (следующие изменения): transactional outbox и внедрённый crash между
COMMIT и publish, backoff с jitter, DLQ и replay, lease зависшего processing, crop и
WebP, очистка staging после фиксации и по retention, замеры перегрузки. Разрыв COMMIT и
publish на этом уровне открыт и назван честно: если процесс API умер между фиксацией
задания и подтверждением брокера, клиент 202 не получил, а строка queued без сообщения
ждёт pipeline-reliability (design, решение 3).
Не меняются: contracts/, tests/, README.md, COURSE.md, lab.json,
CONTRIBUTING.md, MAINTAINERS.md.
Шаг оператора не нужен: make env_setup сам допишет в существующий .env секреты брокера
и ключи worker.
Capabilities
New Capabilities
attachment-processing: фоновая обработка вложения: состояния и переходы, задание, сообщение брокера, доставка at least once, публикация оригинала, thumbnail, идемпотентный эффект, ограниченные повторы, коды ошибок, worker и сохранность принятой работы.message-broker: брокер в стенде: закрепление, volume и пределы, durable-очередь, подтверждение публикации, сохранность при рестарте, клиент в приложении.
Modified Capabilities
attachments: 202 иqueued, порядок записи со staging, заданием и подтверждением брокера, 409 и 404 скачивания, варианты, метаданные, ключи объектов.messages:attachment_ids—queuedиprocessingможно,failed— 409.idempotency: повтор отправленного сообщения, когда его вложение ужеfailed.health: брокер и worker в готовность не входят.data-storage: задания и варианты в PostgreSQL, новые ограничения БД.db-migrations: новые статусы — ослабление ограничения; старый образ на новой схеме.storage-consistency: уборка по ключу staging, текущая работа не тронута; сверка и объекты вариантов.object-storage: пользователь worker в bootstrap, его права, проверки, ключи роли.container-run: брокер и worker в стенде, порты, лимиты, секреты, рестарт.container-image: worker на образе API.graceful-shutdown: остановка worker.service-configuration: секции[broker]и[worker], секреты брокера и ключи worker, консоль и docker.service-logging: журнал worker и отказов публикации, запрет пароля брокера.student-tests: ожиданиеreadyв тестах, сверка покрытия новых capability, worker и очередь вmake test_isolated, брокер и worker на стенде отказов, действия hook, сценарий защиты.load-balancing: цепочка сроков пути загрузки с публикацией.load-benchmark: брокер в профиле загрузок, код успеха варианта.
Impact
- API:
POST …/attachments— 202;GET …/attachments/{id}— четыре статуса,variants,error_code;GET …/content?variant=—originalиthumbnail, 409 и 404;POST …/messages— 409 наfailed. Ломается всё, что ждало 201: собственные тесты, драйвер,bench/k6/uploads.js. - Код:
src/worker/(новый),src/core/services/attachment.py,message.py,attachment_cleanup.py,attachment_reconcile.py, новый сервис обработки, repo заданий и вариантов,attachment_object.py,src/infra/broker/(новый),src/utils/thumbnail.py(новый),src/config/settings.py,src/api/routers/v1/attachment.py,src/api/schemas/,src/api/errors.py,src/main.py,src/infra/logger.py,src/infra/early_stop.py, миграция. - Зависимости:
aio-pika(новая),pillow— из dev-группы в основную,uv.lock. - Стенд:
docker-compose.yml,infra/rabbitmq/rabbitmq.conf,infra/s3/bootstrap.sh,.env.example,config_example.toml,Makefile,scripts/restart.sh,.github/ci/compose.yml,.github/ci/stand-env.sh; шаги.github/workflows/application.ymlте же: стенд поднимаетmake run_docker. - Тесты и инструменты:
student-tests/(клиент, все сценарии вложений, новый модуль обработки,fault_hook.py,run_failures.py,failures.compose.yml,run_isolated.py,spec_coverage.py),bench/(bench.compose.yml,bench.env,run.py,k6/uploads.js,uploads.py),.claude/skills/run-mtusi-messenger/. - Документы: правила
.claude/rules/, карта кодаAGENTS.md,KNOWN_ISSUES.md,REPORT.md,QUESTIONS.md, evidence. - Ресурсы стенда: плюс RabbitMQ 1 CPU / 512 МБ и worker 1 CPU / 1 ГБ; соединений
PostgreSQL плюс два; на время уровня 3 оригинал лежит в S3 дважды (staging и конечный
префикс) до очистки в
pipeline-reliability.