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

143 lines
8.3 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Лабораторная 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 отклоняется.
Подробнее о гарантиях, настройках и ограничениях — в отчёте и руководстве.