Лабораторная 5: очередь и обработка изображений
Мессенджер на FastAPI: PostgreSQL, Redis-сессии, две API-реплики за HAProxy, приватный MinIO, отдельный Redis Streams broker, dispatcher и worker. Автор: Каменский Андрей, БПИ2301. Целевой уровень — 4. Лабораторная продолжает собственную lab4.
Задание · Отчёт · Объяснение и защита · Контракт · Состояния · OpenAPI
Запуск
Нужен Docker с Compose v2. Для публичного smoke достаточно Python 3.9+; для полного набора проверок — Python 3.13 и зависимости проекта.
# Только если .env ещё нет; существующие настройки сохраняем:
python3 scripts/setup-env.py
docker compose config --quiet
docker compose up -d --build --wait
python3 tests/smoke.py
API: http://localhost:8080, документация: http://localhost:8080/docs. На хост опубликован только HAProxy на loopback. Broker, PostgreSQL и MinIO доступны во внутренней сети Compose. Консоль MinIO выключена. Первый build MinIO компилирует закреплённый исходный commit и требует интернета. Bootstrap создаёт приватный bucket и ограниченные S3-учётные записи. Миграции выполняются автоматически до 009.
Существующий .env менять целиком не нужно: у новых настроек есть значения
по умолчанию, полный список находится в .env.example. Для собственного стенда
задайте отдельный S3_WORKER_SECRET_ACCESS_KEY до bootstrap. Старые данные
и их идентификаторы сохраняются; миграция ставит прежние вложения в обработку,
чтобы создать варианты и для них.
Остановка с сохранением всех данных: docker compose down.
Намеренное удаление всех учебных данных выбранного проекта:
docker compose down --volumes. Последнюю команду обычный запуск не требует.
Как работает загрузка
flowchart LR
C[Клиент] --> LB[HAProxy]
LB --> A[API × 2]
A --> S[MinIO: staging]
A --> PG[(PostgreSQL: вложение + job/outbox)]
PG --> D[Dispatcher]
D --> Q[(Redis Streams broker)]
Q --> W[Worker]
S --> W
W --> R[MinIO: оригинал и 3 варианта]
W --> PG
API проверяет доступ, имя, MIME, целостность, 10 MiB и 40 млн пикселей.
После сохранения исходника в S3 и атомарного COMMIT вложения/задания возвращает
202, status=queued. До этого ответа файл полностью передан клиентом.
Недоступность worker или broker не приводит к синхронному resize в API:
задание ждёт в PostgreSQL/outbox.
Dispatcher публикует только ID и служебные данные. Worker берёт ключ исходника
из БД, проверяет его SHA-256, создаёт варианты, сохраняет все объекты и лишь
потом атомарно фиксирует ready с метаданными вариантов. Подтверждение доставки
в Streams следует после COMMIT. Повторы используют те же ключи объектов.
| Вариант | Результат |
|---|---|
| original | Исходные байты PNG/JPEG без изменений |
| thumbnail | JPEG quality=85, до 256×256, пропорции, без увеличения |
| crop | JPEG quality=85, центральный квадрат 128×128, увеличение допустимо |
| optimized | WebP quality=80, method=4, до 1280×1280, без увеличения |
EXIF orientation применяется к производным изображениям; EXIF/XMP/ICC туда не копируются. Прозрачность компонуется на белый RGB-фон. Размеры при вписывании округляются вниз, минимум 1 px. WebP не обязан быть меньше любого исходника.
API
Загрузка — сырые байты, не multipart:
POST /api/v1/chats/{chat_id}/attachments?filename=photo.png.
Нужны Bearer-токен и Content-Type: image/png либо image/jpeg.
GET /api/v1/attachments/{id} показывает queued, processing, ready или
failed. Сообщение может ссылаться на queued/processing; failed отклоняется с 409.
До ready скачивание возвращает 409. После готовности:
GET /api/v1/attachments/{id}/content
GET /api/v1/attachments/{id}/content?variant=thumbnail
GET /api/v1/attachments/{id}/content?variant=crop
GET /api/v1/attachments/{id}/content?variant=optimized
Все варианты читаются через авторизованный API без redirect. Посторонний пользователь получает 404. В публичных метаданных нет S3-ключей и внутренних URL. Сессии, права, пагинация и идемпотентность сообщений из предыдущих работ сохранены.
Проверки
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt -r requirements-dev.txt
make lint check validate PYTHON=.venv/bin/python
make test test-attachments test-lab5 test-idempotency PYTHON=.venv/bin/python
Полная приёмка создаёт новый проект Compose, новые случайные пароли и пустые
volumes на свободном порту. Проверяет миграцию старого вложения, реальные падения,
persistence и failover. В конце удаляет только собственный тестовый проект и
его volumes; сохраняет логи в evidence/lab5-*.txt и сводку lab5-summary.json.
make verify-lab5 PYTHON=.venv/bin/python
Отдельный запуск проверок отказов требует явно выбранного изолированного проекта:
COMPOSE_PROJECT_NAME=my-lab5-test docker compose up -d --build --wait
COMPOSE_PROJECT_NAME=my-lab5-test make test-lab5-faults PYTHON=.venv/bin/python
Эти тесты временно останавливают процессы и включают fault injection; обычная
конфигурация восстанавливается в finally. Публичные tests не подменяют реализацией:
course-tests/ содержит файлы из skeleton lab5 без изменения их проверок.
Неудачные задания и повтор
make jobs-failed
# Подставить job_id из реестра; повтор разрешён только для failed:
docker compose exec -T dispatcher python -m src.pipeline.admin replay JOB_UUID \
--operator student --reason "Хранилище восстановлено"
Повтор сохраняет прежний job_id, увеличивает attempt, начинает новый ограниченный
цикл попыток и пишет audit в job_replays. Ready-задание повторять нельзя.
Failed-исходник хранится семь дней; после очистки staging replay отклоняется.
Подробнее о гарантиях, настройках и ограничениях — в отчёте и руководстве.