Files
mtusi2026lab5/README.md
T

192 lines
12 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.
# Лабораторная 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/concurrent_uploads.py --base-url ... # конкурентные upload
# attachment_flow.py — двухшаговый helper для verify-attachment-failover.sh,
# а не самостоятельный тест: ему нужны --action upload|download и --state.
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` на трёх размерах:
`small_many` (192×128), `exactly_right` (1280×1280, optimized WebP без scaling)
и `huge_few` (2400×1800). Метрики: throughput, queue lag, p95 time-to-ready,
RSS и разложение времени на decode / scale / JPEG / WebP. Результаты и графики —
`evidence/track1.{json,html,md}`, разбор — в [REPORT.md](REPORT.md).
```sh
# Полный прогон: 30 small + 18 exactly_right + 12 huge на профиль.
make track1 BASE_URL=http://localhost:8080
# То же без make.
python3 scripts/track1_experiment.py --base-url http://localhost:8080
# Быстрая проверка механики и/или свои лимиты worker-а.
python3 scripts/track1_experiment.py --small-jobs 5 --exactly-jobs 3 --huge-jobs 3 --skip-backpressure
TRACK1_WORKER_CPU_LIMIT=2.0 TRACK1_WORKER_MEM_LIMIT=3G \
python3 scripts/track1_experiment.py --base-url http://localhost:8080
```
Эксперимент пересоздаёт worker с `WORKER_CONCURRENCY`/`WORKER_PREFETCH`,
поднимает memory limit до 2 GiB (чтобы `eager` не падал по OOM), а в `finally`
возвращает конфигурацию из `.env`. Он управляет только локальным Compose-стендом.
Кратко: на 192×128 eager дал 15.58 jobs/s против 6.84 у serial (2.3×) при RSS
28→32 MiB. На 1280×1280 и 2400×1800 все профили дали ~0.44–0.50 jobs/s:
worker ограничен 1 CPU, а encode share составил 82–83% и 61–64% — сжатие, а не
только scaling, задаёт нижнюю границу. RSS вырос до 818–950 MiB, queue lag p95
упал, но ready p95 остался ~26–36 s. При `MAX_PENDING_JOBS=3` API вернул
`503` + `Retry-After: 5`; после старта worker принятые задания стали ready за
7.65 s.
## Ограничения
Стенд учебный и однокомпонентный по каждому сервису: RabbitMQ и PostgreSQL
запущены в одном экземпляре, поэтому отказ их контейнера проверяется
перезапуском с volume, а не HA-кластером. `MAX_PENDING_JOBS` считается по
каждой API-реплике отдельно, это приблизительный, а не глобальный лимит.
Измерения RSS на Docker Desktop/в CI могут отличаться от bare-metal. Секреты,
tokens и содержимое пользовательских файлов в evidence не сохраняются.