forked from mtusi2026/mtusi2026lab5
143 lines
8.3 KiB
Markdown
143 lines
8.3 KiB
Markdown
# Лабораторная 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 отклоняется.
|
||
Подробнее о гарантиях, настройках и ограничениях — в отчёте и руководстве.
|