Files
mtusi2026lab2/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

36 lines
4.8 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.
## 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 брокера.