# Лабораторная 5: очередь и обработка изображений Мессенджер на FastAPI: PostgreSQL, Redis-сессии, две API-реплики за HAProxy, приватный MinIO, отдельный Redis Streams broker, dispatcher и worker. Автор: **Каменский Андрей, БПИ2301**. Целевой уровень — **4**. Лабораторная продолжает собственную lab4. [Задание](LAB5_TASK.md) · [Отчёт](REPORT.md) · [Объяснение и защита](LAB5_GUIDE.md) · [Контракт](contracts/README.md) · [Состояния](contracts/attachment-states.md) · [OpenAPI](contracts/openapi.json) ## Запуск Нужен Docker с Compose v2. Для публичного smoke достаточно Python 3.9+; для полного набора проверок — Python 3.13 и зависимости проекта. ```sh # Только если .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`. Последнюю команду обычный запуск не требует. ## Как работает загрузка ```mermaid 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. После готовности: ```text 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. Сессии, права, пагинация и идемпотентность сообщений из предыдущих работ сохранены. ## Проверки ```sh 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`. ```sh make verify-lab5 PYTHON=.venv/bin/python ``` Отдельный запуск проверок отказов требует явно выбранного изолированного проекта: ```sh 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 без изменения их проверок. ## Неудачные задания и повтор ```sh 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 отклоняется. Подробнее о гарантиях, настройках и ограничениях — в отчёте и руководстве.