Files
2026-11-17 17:53:23 +03:00

8.3 KiB
Raw Permalink Blame History

Лабораторная 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 отклоняется. Подробнее о гарантиях, настройках и ограничениях — в отчёте и руководстве.