- 3 profiles (serial 1/1, balanced 4/4, eager 8/32) x 2 image sizes - measure throughput, DB-derived queue lag and p95 time-to-ready, worker RSS - separate MAX_PENDING_JOBS=3 backpressure and worker recovery run - self-contained HTML/SVG dashboard plus JSON/Markdown evidence - document methodology, results and limitations in REPORT/README/CHANGELOG
12 KiB
Лабораторная 5. Очереди и асинхронная обработка изображений
Реализация лабораторной 5 на Go: API принимает файл, сохраняет оригинал в durable staging, фиксирует задание в PostgreSQL и отвечает 202. Отдельный worker обрабатывает задание через RabbitMQ и делает варианты изображения. Целевая оценка — 5, трек 1 (очередь под перегрузкой).
Карта курса · Процесс fork/PR · OpenAPI · Семантика API · Проверки · Отчёт · Примеры JSON · Changelog
Стек и состав стенда
| Компонент | Версия | Роль |
|---|---|---|
| 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+ для проверок.
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, соберите приложение на хосте и запустите без сборки:
DOCKER_BUILDKIT=1 docker build --network=host -t mtusi2026lab-api:local .
docker compose --env-file .env up -d --no-build
Как устроен путь файла
- API / upload. Проверяются членство в чате, имя и
Content-Type, затем тело потоково копируется в temp-файл (буфер 32 KiB) с SHA-256. Байтовый лимит 10 MiB и пиксельный лимит 40 MP проверяются до выделения памяти под декодирование. Валидный оригинал кладётся вstaging/{chat}/{attachment}. - Одна транзакция. В PostgreSQL вставляются
attachments(queued) иattachment_jobs(published_at IS NULL). Только после COMMIT клиент получает202; в этот момент durable уже и байты, и намерение. - Outbox → RabbitMQ. Каждая API-реплика (и worker) раз в 250 мс публикует
непубликованные строки в quorum queue с persistent delivery и ждёт publisher
confirm. Затем
published_atвыставляется compare-and-set. Падение между COMMIT и publish восстанавливается следующим проходом. - Worker. Сообщение содержит только
job_id,attachment_id, версию и попытку — без байтов, ключей и credentials. Worker берёт DB-lease, заново читает доверенные метаданные, сверяет размер и SHA-256 staging-объекта. - Эффект. Оригинал копируется без изменений в
attachments/...; рядом пишутся детерминированные вариантыthumbnail,crop,optimized.CompleteJobатомарно ставитreadyтолько для текущей попытки/версии. Лишь после этого staging удаляется, а сообщение подтверждается (ack). - Клиент опрашивает
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 |
детерминированные хуки для доказательств |
Проверки и доказательства
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 на маленьких и
больших изображениях, измеряет throughput, queue lag, p95 time-to-ready и RSS,
затем отдельно показывает backpressure и восстановление. Результаты и графики —
evidence/track1.{json,html,md}, разбор — в REPORT.md.
# Полный прогон: 30 small + 12 huge на каждый профиль, затем backpressure.
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 --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-стендом и не предназначен для production.
Кратко: на 192×128 eager дал 13.86 jobs/s против 6.88 у serial (2×) при RSS
28→33 MiB. На 2400×1800 все профили дали ~0.45 jobs/s (worker ограничен 1 CPU),
но RSS вырос 205→1122 MiB, а queue lag p95 упал 23.3→17.5 s: concurrency меняет
latency/ресурсы, а не throughput CPU-bound задач. При MAX_PENDING_JOBS=3
четвёртый upload получил 503 + Retry-After: 5; после старта worker три
принятых задания стали ready за 7.6 s.
Ограничения
Стенд учебный и однокомпонентный по каждому сервису: RabbitMQ и PostgreSQL
запущены в одном экземпляре, поэтому отказ их контейнера проверяется
перезапуском с volume, а не HA-кластером. MAX_PENDING_JOBS считается по
каждой API-реплике отдельно, это приблизительный, а не глобальный лимит.
Измерения RSS на Docker Desktop/в CI могут отличаться от bare-metal. Секреты,
tokens и содержимое пользовательских файлов в evidence не сохраняются.