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