feat(lab5): durable async attachment pipeline through grade 4

- RabbitMQ quorum queue, persistent messages and publisher confirms
- S3 staging plus PostgreSQL attachments/jobs outbox transaction
- worker variants (thumbnail, crop, optimized WebP), DB lease and lease sweeper
- jittered retry, permanent failures, explicit replay and admission cap
- deterministic crash hooks, resilience script and evidence for grade 4
- async-aware custom tests, oversized pixel case, docs and changelog
This commit is contained in:
Mikhail Verkovykh
2026-11-15 00:30:36 +03:00
parent 28d68dc30b
commit 9e43faa536
48 changed files with 4077 additions and 333 deletions
+135 -76
View File
@@ -1,105 +1,164 @@
# Лабораторная 5. Очереди и асинхронная обработка изображений
Отделить приём файла от тяжёлой обработки, корректно переживать повторную доставку и остановку worker.
Реализация лабораторной 5 на Go: API принимает файл, сохраняет оригинал в
durable staging, фиксирует задание в PostgreSQL и отвечает **202**. Отдельный
worker обрабатывает задание через RabbitMQ и делает варианты изображения.
Целевая оценка — **5, трек 1** (очередь под перегрузкой).
Это **skeleton**, а не готовый сервер. Здесь есть задание, контракт и публичные проверки. Реализацию приложения, Dockerfile и требуемую инфраструктуру пишет студент. Язык и framework свободные; UI не обязателен.
[Карта курса](COURSE.md) · [Процесс fork/PR](CONTRIBUTING.md) · [OpenAPI](contracts/openapi.json) · [Семантика API](contracts/README.md) · [Проверки](tests/README.md) · [Отчёт](REPORT.md) · [Примеры JSON](contracts/examples.json) · [Changelog](CHANGELOG.md)
[Карта курса](COURSE.md) · [Процесс fork/PR](CONTRIBUTING.md) · [OpenAPI](contracts/openapi.json) · [Семантика API](contracts/README.md) · [Проверки](tests/README.md) · [Отчёт](REPORT.md) · [Примеры JSON](contracts/examples.json) · [Памятка преподавателю](MAINTAINERS.md)
## Стек и состав стенда
## Откуда начинаем
| Компонент | Версия | Роль |
| --- | --- | --- |
| Go + Fiber v3 | Go 1.27.1 | API, worker, reconciler |
| PostgreSQL | 16.10 | источник истины: attachments, jobs/outbox, idempotency |
| RabbitMQ | 4.2 | durable quorum queue `attachment.process.v1` |
| RustFS (S3) | 1.0.4 | staging и конечные объекты, private bucket |
| Redis | 7.4.7 | сессии |
| HAProxy | 3.2.6 | балансировка двух API-реплик |
Нужен минимум lab4. POST upload теперь возвращает 202 queued, а готовность выясняется через метаданные. В HTTP upload клиент по-прежнему передаёт все байты.
Контейнеры: `postgres`, `redis`, `rustfs`, `s3-init`, `migrate`, два `api`,
`worker`, `reconciler`, `haproxy`. Секреты живут только в локальном `.env`.
**Архитектура:** API → устойчивый staging + запись задания → брокер → worker → конечный S3 + PostgreSQL. Клиент опрашивает статус.
## Запуск из чистого clone
## Что сделать
1. Выберите RabbitMQ, Redis/Valkey Streams, NATS JetStream или другой брокер с persistence и подтверждениями. Обычный Pub/Sub без хранения не подходит.
2. Разделите приём, durable staging, публикацию задания, обработку и фиксацию результата. Прочитайте contracts/attachment-states.md.
3. Реализуйте worker отдельно от API: публикация оригинала в конечный S3-prefix и thumbnail 256×256 по правилам контракта.
4. Добавьте конечные состояния, ограниченные повторы и идемпотентную запись результатов. Не помещайте bytes или credentials в сообщения брокера.
5. Остановите worker, загрузите файл, перезапустите API/worker, убедитесь в завершении принятой задачи. Затем проверьте повторную доставку.
## Оценка «3»: работающий минимум
- Весь минимум lab4 сохранён с переходом upload 201 → 202. API возвращает 202 только после устойчивого приёма оригинала и сохранения задания; остановка API после ответа не теряет работу.
- В общем Compose/Swarm есть отдельные broker и worker. Сообщения durable, доставка at least once, подтверждение только после устойчивого эффекта. Недоступность worker не заставляет API выполнять resize синхронно.
- Состояния queued/processing/ready/failed доступны в API. Worker сохраняет оригинал и один thumbnail; original неизменен, thumbnail соответствует контракту. Публичный smoke проходит.
- Есть ограниченный retry (конкретное число попыток в конфигурации, например 5), финальное failed с безопасным error_code. Повтор одной job не создаёт второго набора вариантов.
- Демонстрация: worker остановлен → upload 202 → сообщение с вложением создано → API перезапущен → worker запущен → ready и доступный thumbnail. Принятое задание не исчезает при рестарте broker с volume.
## Оценка «4»: уровень стажёра/джуна
Весь уровень 3 **и все** пункты ниже:
- Добавлены crop 128×128 и optimized WebP по контракту, параметры качества/удаления метаданных описаны. Невалидные/огромные изображения ограничены по bytes, пикселям, времени и памяти worker.
- Разрыв между PostgreSQL и broker закрыт transactional outbox или другой доказанной схемой восстановления намерения. Внедрён crash между COMMIT и publish; после восстановления задача доходит до ready без ручного создания нового задания.
- Retry использует backoff с jitter, различает постоянные/временные ошибки; есть DLQ/реестр failed и безопасный явный replay. «Повторить» не означает безусловно исполнить дубль уже успешной job.
- Проверена остановка worker после записи объекта, но до ack; повтор завершает тот же результат. Есть timeout/lease для зависшего processing, ограниченная конкуренция/prefetch и очистка staging после безопасной фиксации.
## Оценка «5»: исследование и доказанный результат
Весь уровень 4 **и один законченный трек на выбор**. Приведите гипотезу, повторяемую методику, результаты и ограничения.
**Трек 1. Очередь под перегрузкой.** Сравните ≥3 настройки concurrency/prefetch на разных размерах изображений. Измерьте throughput, queue lag, p95 времени до ready и RSS; покажите backpressure и ограничение количества принятой работы. Докажите восстановление после перегрузки, объясните компромисс latency/ресурсы.
**Трек 2. Доказанная идемпотентность pipeline.** Постройте versioned pipeline и автоматический fault-injection для дубля, reorder, crash до/после side effect и устаревшей job после новой версии. Зафиксируйте инварианты, покажите отсутствие потери подтверждённых задач и перезаписи нового результата старым. Обсудите почему это не exactly-once доставка.
## Как начать и проверить
Нужны Docker Engine с Compose v2 и Python 3.9+ для проверок.
```sh
# Работает прямо в skeleton, Python 3.9+; приложение не запускается:
make check
cp .env.example .env
# После реализации запустите свой сервер/стенд по REPORT.md.
# По умолчанию тест использует http://localhost:8080.
make test
```
# Заполните только секреты; S3_ACCESS_KEY_ID и S3_APP_USER должны совпадать.
python3 - <<'PY'
from pathlib import Path
import secrets
p = Path(".env")
text = p.read_text()
for key in ("POSTGRES_PASSWORD", "S3_ROOT_ACCESS_KEY", "S3_ROOT_SECRET_KEY",
"S3_SECRET_ACCESS_KEY", "RABBITMQ_PASSWORD"):
text = "\n".join(
f"{key}={secrets.token_urlsafe(24)}" if line.startswith(key + "=") else line
for line in text.splitlines()
) + "\n"
p.write_text(text)
PY
`.env.example`, `compose.example.yaml` и `contracts/infrastructure.json` описывают настройки и роли компонентов. **compose.example.yaml — список ролей с пустым services, не запускаемый стенд.** Реализуйте свой `compose.yaml`/`stack.yaml`, закрепите версии образов, заполните локальный `.env` и опишите bootstrap/миграции. Все зависимости поднимаются из этого репозитория; ссылка «у меня БД уже установлена» не заменяет воспроизводимость.
```sh
# Compose-вариант после реализации:
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# Дождитесь /health/ready; затем make test.
# Для Swarm укажите эквивалентные build/push/deploy-команды в REPORT.md.
# Дождитесь healthy у api/worker и 200 от readiness.
curl -fsS http://localhost:8080/health/ready
make test BASE_URL=http://localhost:8080
```
`migrate` применяет миграции 0001–0005, `s3-init` идемпотентно создаёт private
bucket и scoped-пользователя. Повторный `up -d` не удаляет volumes. Полная
остановка без потери данных — `docker compose down`; намеренное удаление
учебных данных — `docker compose down -v` (разрушительно).
Примеры запросов доступны в `examples/requests.http`, примеры JSON — в `contracts/examples.json`. Для полной проверки схемы (по желанию локально; CI делает её автоматически):
Если Docker не может скачать базовые образы из-за DNS, соберите приложение на
хосте и запустите без сборки:
```sh
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python
DOCKER_BUILDKIT=1 docker build --network=host -t mtusi2026lab-api:local .
docker compose --env-file .env up -d --no-build
```
Smoke не выставляет оценку автоматически. Проверку сохранности/отказов запускайте явно по [tests/README.md](tests/README.md), остальные доказательства приведите в отчёте.
## Как устроен путь файла
## Сценарий защиты
1. **API / upload.** Проверяются членство в чате, имя и `Content-Type`, затем
тело потоково копируется в temp-файл (буфер 32 KiB) с SHA-256. Байтовый
лимит 10 MiB и пиксельный лимит 40 MP проверяются до выделения памяти под
декодирование. Валидный оригинал кладётся в `staging/{chat}/{attachment}`.
2. **Одна транзакция.** В PostgreSQL вставляются `attachments` (`queued`) и
`attachment_jobs` (`published_at IS NULL`). Только после COMMIT клиент
получает `202`; в этот момент durable уже и байты, и намерение.
3. **Outbox → RabbitMQ.** Каждая API-реплика (и worker) раз в 250 мс публикует
непубликованные строки в quorum queue с persistent delivery и ждёт publisher
confirm. Затем `published_at` выставляется compare-and-set. Падение между
COMMIT и publish восстанавливается следующим проходом.
4. **Worker.** Сообщение содержит только `job_id`, `attachment_id`, версию и
попытку — без байтов, ключей и credentials. Worker берёт DB-lease, заново
читает доверенные метаданные, сверяет размер и SHA-256 staging-объекта.
5. **Эффект.** Оригинал копируется без изменений в `attachments/...`; рядом
пишутся детерминированные варианты `thumbnail`, `crop`, `optimized`.
`CompleteJob` атомарно ставит `ready` только для текущей попытки/версии.
Лишь после этого staging удаляется, а сообщение подтверждается (ack).
6. **Клиент** опрашивает `GET /api/v1/attachments/{id}` до `ready`; content
отдаётся только для `ready`, иначе `409`.
1. Запустить make test: API возвращает 202, GET доходит до ready, оригинал и настоящий JPEG thumbnail проверяются.
2. Остановить worker своим скриптом, загрузить файл, убедиться, что content отвечает 409, а другие сообщения продолжают работать.
3. Перезапустить API/broker с сохранением volumes, запустить worker; та же запись должна стать ready. Зафиксировать порядок действий и ID без токенов.
4. Для 4: воспроизвести crash после side effect до ack, разрыв COMMIT/publish и replay failed; для 5 — выбранный эксперимент.
### Варианты
## Что должно быть в PR
| Имя | Формат | Правило |
| --- | --- | --- |
| `thumbnail` | JPEG q=85 | fit в 256×256, белый фон, без upscale |
| `crop` | JPEG q=85 | центральный квадрат 128×128 |
| `optimized` | WebP q=82 | fit в 1280×1280, без upscale |
Worker, брокер в общем стенде, схема jobs, migrations/outbox по уровню, конфигурация retry, тесты сбоев и отчёт.
EXIF orientation применяется до преобразований. Оригинал сохраняется
byte-for-byte и сохраняет исходный SHA-256. Метаданные вариантов не
копируются. Все операции детерминированы: повторная доставка перезаписывает
те же ключи теми же байтами.
Заполните `REPORT.md` и [шаблон PR](.github/pull_request_template.md), укажите целевую оценку/трек. Не меняйте обязательный контракт и публичные tests ради зелёного результата. Сохраняйте возможности предыдущих лабораторных в пределах [объявленных переходов](COURSE.md).
### Надёжность и повторы
## Вопросы на защите
- Очередь — RabbitMQ quorum queue, сообщения persistent, publisher confirms.
- Ack только после durable effect (или осознанного no-op). `ErrRequeue`
используется, если не удалось записать состояние в PostgreSQL.
- Ошибки делятся на постоянные и временные. Временные повторяются с
экспоненциальным backoff ±50% jitter, до `JOB_MAX_ATTEMPTS`.
- Постоянная ошибка даёт `failed` с безопасным `error_code`; реестр failed
виден через API, явный replay — `worker -replay <attachment_uuid>`.
- Просроченный lease (`processing` без живого worker) возвращается в очередь
sweeper-ом. Повтор не создаёт второй набор вариантов.
- `MAX_PENDING_JOBS` — приблизительный admission cap: при переполнении upload
получает `503` и `Retry-After: 5`, не доходя до чтения тела.
- Reconciler удаляет только брошенные staging/pending-объекты после grace
period; готовые вложения не трогает.
- Чем publisher confirm отличается от consumer ack?
- Что именно уже сохранено в момент 202?
- Почему повторная доставка нормальна и где находится ключ идемпотентности job?
- Как отличить зависший worker от долго работающего и не запустить два неконтролируемых дубля?
## Конфигурация
## Первичные материалы
Все переменные и значения по умолчанию перечислены в `.env.example`. Главные:
- [RabbitMQ reliability](https://www.rabbitmq.com/docs/reliability)
- [Publisher confirms and acknowledgements](https://www.rabbitmq.com/docs/confirms)
- [Redis Streams](https://redis.io/docs/latest/develop/data-types/streams/)
- [NATS JetStream](https://docs.nats.io/nats-concepts/jetstream)
| Переменная | Смысл |
| --- | --- |
| `MAX_UPLOAD_BYTES` | байтовый лимит, не больше 10 MiB |
| `MAX_IMAGE_PIXELS` | пиксельный лимит, не больше 40 MP |
| `IMAGE_DECODE_MEMORY_MB` | общий budget декодирования на процесс |
| `WORKER_CONCURRENCY` / `WORKER_PREFETCH` | параллелизм handler-ов / unacked сообщений |
| `MAX_PENDING_JOBS` | admission cap очереди (0 — выключен) |
| `JOB_MAX_ATTEMPTS`, `JOB_TIMEOUT_SECONDS`, `JOB_LEASE_SECONDS` | retry/lease policy |
| `JOB_RETRY_BASE_SECONDS`, `JOB_RETRY_MAX_SECONDS` | backoff |
| `WORKER_FAULT_MODE`, `WORKER_CRASH_AFTER_EFFECT`, `WORKER_CRASH_AFTER_CLAIM` | детерминированные хуки для доказательств |
## Проверки и доказательства
```sh
make check
make test BASE_URL=http://localhost:8080 # публичный smoke
python3 tests/custom/attachments.py --base-url ... # 413/415/404/400, без 5xx
python3 tests/custom/attachment_flow.py --base-url ... # сквозной upload/download
python3 tests/custom/concurrent_uploads.py --base-url ... # конкурентные upload
python3 scripts/lab5_resilience.py --base-url ... # 6 сценариев уровня 4
python3 scripts/track1_experiment.py # трек 1 уровня 5
```
`scripts/lab5_resilience.py` останавливает worker и RabbitMQ, внедряет crash
до/после эффекта, проверяет retry, replay и lease recovery. Результаты —
`evidence/lab5-grade4.{json,md}`. Persistence/failover проверяются публичными
`make test-persistence` / `make test-failover` с `scripts/restart.sh` и
`scripts/stop-one.sh`; см. `evidence/lab5-persistence*` и `evidence/lab5-failover.txt`.
Трек 1 запускает матрицу профилей `serial/balanced/eager` на маленьких и
больших изображениях, измеряет throughput, queue lag, p95 time-to-ready и RSS,
затем отдельно показывает backpressure и восстановление. Результаты и графики
описаны в [REPORT.md](REPORT.md).
## Ограничения
Стенд учебный и однокомпонентный по каждому сервису: RabbitMQ и PostgreSQL
запущены в одном экземпляре, поэтому отказ их контейнера проверяется
перезапуском с volume, а не HA-кластером. `MAX_PENDING_JOBS` считается по
каждой API-реплике отдельно, это приблизительный, а не глобальный лимит.
Измерения RSS на Docker Desktop/в CI могут отличаться от bare-metal. Секреты,
tokens и содержимое пользовательских файлов в evidence не сохраняются.