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

10 KiB
Raw Blame History

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.