forked from mtusi2026/mtusi2026lab5
- 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
165 lines
10 KiB
Markdown
165 lines
10 KiB
Markdown
# Лабораторная 5. Очереди и асинхронная обработка изображений
|
||
|
||
Реализация лабораторной 5 на Go: API принимает файл, сохраняет оригинал в
|
||
durable staging, фиксирует задание в PostgreSQL и отвечает **202**. Отдельный
|
||
worker обрабатывает задание через RabbitMQ и делает варианты изображения.
|
||
Целевая оценка — **5, трек 1** (очередь под перегрузкой).
|
||
|
||
[Карта курса](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)
|
||
|
||
## Стек и состав стенда
|
||
|
||
| Компонент | Версия | Роль |
|
||
| --- | --- | --- |
|
||
| 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-реплик |
|
||
|
||
Контейнеры: `postgres`, `redis`, `rustfs`, `s3-init`, `migrate`, два `api`,
|
||
`worker`, `reconciler`, `haproxy`. Секреты живут только в локальном `.env`.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Нужны Docker Engine с Compose v2 и Python 3.9+ для проверок.
|
||
|
||
```sh
|
||
cp .env.example .env
|
||
|
||
# Заполните только секреты; 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
|
||
|
||
docker compose --env-file .env up -d --build
|
||
# Дождитесь 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` (разрушительно).
|
||
|
||
Если Docker не может скачать базовые образы из-за DNS, соберите приложение на
|
||
хосте и запустите без сборки:
|
||
|
||
```sh
|
||
DOCKER_BUILDKIT=1 docker build --network=host -t mtusi2026lab-api:local .
|
||
docker compose --env-file .env up -d --no-build
|
||
```
|
||
|
||
## Как устроен путь файла
|
||
|
||
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`.
|
||
|
||
### Варианты
|
||
|
||
| Имя | Формат | Правило |
|
||
| --- | --- | --- |
|
||
| `thumbnail` | JPEG q=85 | fit в 256×256, белый фон, без upscale |
|
||
| `crop` | JPEG q=85 | центральный квадрат 128×128 |
|
||
| `optimized` | WebP q=82 | fit в 1280×1280, без upscale |
|
||
|
||
EXIF orientation применяется до преобразований. Оригинал сохраняется
|
||
byte-for-byte и сохраняет исходный SHA-256. Метаданные вариантов не
|
||
копируются. Все операции детерминированы: повторная доставка перезаписывает
|
||
те же ключи теми же байтами.
|
||
|
||
### Надёжность и повторы
|
||
|
||
- Очередь — 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; готовые вложения не трогает.
|
||
|
||
## Конфигурация
|
||
|
||
Все переменные и значения по умолчанию перечислены в `.env.example`. Главные:
|
||
|
||
| Переменная | Смысл |
|
||
| --- | --- |
|
||
| `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 не сохраняются.
|