# Отчёт — лабораторная 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) и размерами