Files
mtusi2026labs/openspec/changes/add-lab5-async-attachments/proposal.md
T
ArtyomandClaude Opus 5.5 d9bcc7324b Propose asynchronous attachment processing as an openspec change
Plan grade 3 of lab 5: upload answers 202 queued after the original is
in a private staging prefix and the attachment, its job and an outbox
row are committed in one transaction; a separate relay publishes the
outbox to a RabbitMQ quorum queue with publisher confirms and returns
jobs with an expired lease; a separate worker on FastStream claims a
job under a lease, publishes the original and a 256 px JPEG thumbnail,
commits the result fenced by the lease token and acks only after the
commit, retries transient errors up to JOB_MAX_ATTEMPTS and fails
undecodable images at once. Content answers 409 until ready and a
failed attachment cannot be sent.

The change adds the lab5-attachment-pipeline and lab5-job-delivery
capabilities and deltas to lab4-attachments, lab4-upload-resilience,
lab1-messenger-history and lab3-load-balancing.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-29 00:42:15 +03:00

4.8 KiB
Raw Blame History

Why

Решение лабы 4 обрабатывает вложение синхронно и отвечает 201 ready. Рубрика «3» лабы 5 требует отделить приём от обработки: 202 queued после устойчивого staging и задания, отдельные broker и worker, at-least-once с ack после эффекта, состояния queued/processing/ready/failed, thumbnail, ограниченный retry, повтор job без второго набора вариантов, демонстрацию остановки worker и рестарта брокера. Изменение закрывает уровень «3» и строки 3.1–3.8 REPORT.md.

What Changes

  • BREAKING (объявленный переход 4 → 5): upload отвечает 202 со снимком queued; оригинал сначала пишется в приватный префикс staging/, затем одной транзакцией фиксируются вложение queued, задание (pipeline_version 1, attempt 1) и строка outbox. API не обрабатывает изображение и не подключается к брокеру.
  • GET /attachments/{id} показывает текущий статус и варианты опубликованной версии; /content до ready — 409, нет варианта — 404. failed в сообщении — 409.
  • Процесс relay: outbox → RabbitMQ (publisher confirm, mandatory, persistent), возврат истёкших аренд, уборка staging.
  • Процесс worker (тот же образ, FastStream поверх aio-pika): захват арендой, оригинал в originals/, thumbnail, фиксация с fencing, ack после COMMIT; временная ошибка → queued с backoff, после JOB_MAX_ATTEMPTS → failed retry_exhausted; повтор завершённой job — no-op.
  • Миграция 0004_jobs.sql: статусы и ключи вложений, attachment_variants, jobs, outbox, job_events.
  • Стенд: broker (RabbitMQ 4.1.8, quorum queue, DLX, volume), relay, worker, раздельные права; обвязка из .prep/lab5.

Capabilities

New Capabilities

  • lab5-attachment-pipeline: состояния вложения, обработка заданий worker, thumbnail, retry и финальные ошибки, идемпотентный эффект, аренда, staging, демонстрация остановки worker.
  • lab5-job-delivery: брокер в стенде, outbox и relay, формат сообщения, at-least-once, права клиентов брокера, переживание рестарта брокера, отдельные процессы relay и worker.

Modified Capabilities

  • lab4-attachments: «Загрузка оригинала в чат» — 202 queued; «Метаданные и скачивание только участникам» — статусы, варианты, 409; «Порядок записи PostgreSQL и S3» — staging и задание.
  • lab4-upload-resilience: «Компенсация сбоя после записи объекта» — фиксация в очередь вместо ready.
  • lab1-messenger-history: «Отправка сообщения» — failed-вложение даёт 409.
  • lab3-load-balancing: «Рестарт стенда» — перезапускаются и брокер, relay, worker.

Impact

  • Код: зона attachments (домен заданий, порты брокера и рендера, адаптеры FastStream и Pillow, точки входа relay и worker), messaging (порт состояния вложений), main.py, новые сборки relay.py и worker.py; зависимости faststream[rabbit], dishka-faststream.
  • Стенд: compose.yaml, infra/rabbitmq/, infra/s3/, scripts/, Makefile, .env.example, CI.
  • Тесты: pipeline против одноразового PostgreSQL, рендер thumbnail, формат сообщения по jobs.schema.json, API 202/409.
  • Отчёт: строки уровня «3» REPORT.md, evidence/.

Non-goals

Crop и optimized, лимиты worker по времени и памяти, crash-точки окон 2–5, jitter в backoff, DLQ-демонстрация и replay, heartbeat аренды и retention failed — уровень «4», следующее изменение; versioned pipeline — трек 2. Из Out of scope не появляется ничего: метрики и трассировка (лаба 6), TLS (лаба 7), admission control (трек 1), HA брокера.