# Лабораторная 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 `. - Просроченный 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 не сохраняются.