# 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`.