Files
mtusi2026lab5/README.md
T
Mikhail Verkovykh fec2882c9a feat(lab5): track 1 queue experiment and evidence
- 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
2026-11-15 00:44:45 +03:00

12 KiB
Raw Blame History

Лабораторная 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

Как устроен путь файла

  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 детерминированные хуки для доказательств

Проверки и доказательства

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 не сохраняются.