Files
2026-11-16 20:54:49 +03:00

73 lines
7.7 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
- Автор, группа: Бондаренко Мария, БПИ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) и размерами