forked from mtusi2026/mtusi2026lab5
73 lines
7.7 KiB
Markdown
73 lines
7.7 KiB
Markdown
# Отчёт — лабораторная 5
|
||
|
||
- Автор, группа: Бондаренко Мария, БПИ2302
|
||
- Целевая оценка: 4
|
||
|
||
## Архитектура и решения
|
||
|
||
Система построена по микросервисной/событийно-ориентированной схеме с разделением синхронного HTTP API и асинхронного фонового обработчика медиафайлов:
|
||
|
||
1. API-сервисы (api-1, api-2):
|
||
- Реализованы на базе FastAPI, балансируются через Nginx
|
||
- При загрузке изображения выполняют первичную валидацию сигнатур (PNG/JPEG), проверку размера и разрешения
|
||
- Сохраняют исходный файл во временную зону объектного хранилища S3
|
||
- В рамках единой транзакции PostgreSQL фиксируют метаданные вложения в таблице attachments и записывают событие в таблицу outbox
|
||
2. Транзакционный Outbox:
|
||
- Фоновый поток в API-инстансах вычитывает неопубликованные записи, отправляет задачи в стрим брокера attachment_jobs и проставляет published_at. Это исключает потерю задач при сбое между COMMIT в БД и публикацией в брокер
|
||
3. Брокер сообщений:
|
||
- Запущен с включенной персистентностью
|
||
- Используются Consumer Groups для балансировки нагрузки между воркерами и подтверждения обработки
|
||
4. Объектное хранилище:
|
||
- Хранит временные файлы в staging/ и финальные артефакты в attachments/{chat_id}/{attachment_id}/{variant}
|
||
5. Фоновый обработчик:
|
||
- Многопоточный воркер
|
||
- Вычитывает задачи пачками и обрабатывает их идемпотентно с блокировкой строки в БД
|
||
|
||
## Пайплайн обработки изображений и варианты (Variants)
|
||
|
||
Перед генерацией производных форматов исходное изображение проходит нормализацию:
|
||
- EXIF-ориентация: применяется ImageOps.exif_transpose(img) для корректного поворота фотографий с мобильных устройств перед ресайзом и кропом
|
||
- Цветовое пространство: изображения с альфа-каналом (RGBA, LA, P с прозрачностью) накладываются на белый фон (255, 255, 255) и приводятся к RGB
|
||
- Защита от Decompression Bomb: установлено ограничение Image.MAX_IMAGE_PIXELS = 40000000
|
||
|
||
## Спецификация генерируемых вариантов (Grade 4):
|
||
1. thumbnail (превью для списка/чата):
|
||
- Формат и качество: image/jpeg, quality=85, optimize=True.
|
||
- Геометрия: пропорциональное масштабирование с вписыванием в квадрат 256256 пикселей (без апскейла, если оригинал меньше)
|
||
2. optimized (оптимизированный просмотр):
|
||
- Формат и качество: image/webp, quality=85.
|
||
- Геометрия: пропорциональное масштабирование с вписыванием в рамку 12801280 пикселей (без апскейла)
|
||
3. crop (квадратная миниатюра/аватар):
|
||
- Формат и качество: image/jpeg, quality=85, optimize=True.
|
||
- Геометрия: центральное квадратное кадрирование с последующим приведением к точному размеру 128128 пикселей
|
||
|
||
|
||
## Отказоустойчивость, ретраи и восстановление
|
||
|
||
Для обеспечения надежности уровня на оценку 4 реализованы следующие механизмы:
|
||
|
||
- Разделение ошибок (Permanent / Transient):
|
||
- Постоянные ошибки сразу переводят вложение в терминальный статус failed с соответствующим error_code и подтверждаются в брокере без бесполезных повторов
|
||
- Временные ошибки обрабатываются с повторами до 5 раз
|
||
- Exponential Backoff + Jitter:
|
||
- Перед постановкой следующей попытки ыполняется задержка для предотвращения лавинообразной нагрузки на S3/БД
|
||
- Dead Letter Queue (DLQ) и ручной Replay:
|
||
- При исчерпании попыток вложение получает статус failed, а сообщение перекладывается в отдельный стрим attachment_jobs_dlq
|
||
- Реализован эндпоинт POST /api/v1/attachments/{attachment_id}/replay, который сбрасывает счетчик попыток, переводит статус обратно в queued и транзакционно создает новую задачу в outbox
|
||
- Защита от зависаний:
|
||
- Каждая задача ограничена по времени выполнения (30 секунд).
|
||
- Фоновый цикл воркера каждые 15 секунд вызывает XAUTOCLAIM, перехватывая зависшие сообщения от упавших экземпляров воркеров
|
||
- Очистка временного хранилища:
|
||
- Воркер периодически (раз в 10 минут) сканирует префикс staging/ в S3 и удаляет осиротевшие объекты старше 1 часа.
|
||
|
||
## Результаты проверки и артефакты
|
||
|
||
1. Контрактные и функциональные тесты:
|
||
- scripts/check_contract.py — подтверждено соответствие спецификации OpenAPI, наличие заголовков X-Request-Id и X-Instance-Id
|
||
- tests/smoke.py (evidence/smoke.txt) — пройден полный публичный сценарий
|
||
2. Демонстрация асинхронности и переживания рестартов:
|
||
- При остановленном контейнере worker (demo-01c-worker-stopped.txt) загружен файл sample.png (9becbd32-e413-417a-8762-79bcc195e296), получен ответ 202 Accepted со статусом queued (demo-02-uppload-202.json).
|
||
- Выполнены рестарты API-реплик (demo-04-api-restarted.txt) и брокера Redis (demo-08-after-broker-restart.json).
|
||
- После запуска воркера (demo-05-worker-started.txt) задача успешно обработана из персистентной очереди, статус перешел в ready (demo-06-ready.json), а вариант thumbnail корректно отдан клиенту (demo-07-thumbnail.jpg).
|
||
3. Артефакты расширенного пайплайна:
|
||
- Сформированы и верифицированы все три варианта (g4-variants.txt, g4-thunbnail.jpg, g4-crop.jpg) с корректными MIME-типами (image/jpeg, image/webp) и размерами |