Files
mtusi2026lab5/openspec/changes/async-attachments/proposal.md
T
2026-10-31 04:06:09 +03:00

125 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`.