21 KiB
Отчёт — лабораторная 5
- Автор, группа: Хуцаева Айса, БПИ2302.
- Целевая оценка: 4.
- Commit/PR: solution/khutsaeva-bpi2302
Подготовка
После клонирования репозитория перейти в его корень.
Создать локальный файл конфигурации:
Copy-Item .env.example .env
Заполнить в .env пароли PostgreSQL, Redis, RabbitMQ, административной учётной записи MinIO и отдельной учётной записи API. Для генерации каждого нового пароля можно использовать:
python -c "import secrets; print(secrets.token_hex(24))"
Секреты не добавляются в Git и не включаются в отчёт. В .env.example должны находиться только примеры и безопасные значения по умолчанию.
Для запуска тестов подготовить Python-окружение:
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install jsonschema openapi-spec-validator
$env:PYTHONUTF8 = "1"
Режим UTF-8 необходим, чтобы чтение контрактов на Windows не зависело от системной кодировки CP1251. Перед запуском проверить, что команда python3, используемая Makefile, доступна и видит зависимости тестов.
Сборка и запуск
Проверить Compose:
docker compose config --quiet
Собрать приложение и MinIO:
docker compose build api minio
Запустить стенд:
docker compose up -d --no-build --pull never --scale api=2 --wait --wait-timeout 240
При первом запуске предварительно загрузить внешние образы:
docker compose pull postgres redis migrate lb rabbitmq
Если запуск выполняется впервые, эту команду следует выполнить до docker compose up.
Миграции выполняет отдельный сервис migrate. Сервис minio-init создаёт приватный bucket и настраивает права отдельной учётной записи приложения. Успешное завершение этих двух сервисов со статусом Exited (0) является нормальным.
Проверить состояние:
docker compose ps -a
curl.exe -i http://localhost:8080/health/ready
Основной адрес API — http://localhost:8080. Запросы проходят через HAProxy. Прямой доступ к портам API и worker с хоста не требуется.
Если стенд лабораторной 4 использует тот же порт, сначала остановить его из каталога соответствующего проекта.
Проверки
Проверка обработчика изображений внутри worker:
docker compose exec -T worker /opt/images/bin/python /app/selftest.py
Публичные проверки:
make check
make validate
make test
Сценарии отказов уровня 4:
python3 -X utf8 tests/level4_check.py --base-url http://localhost:8080 --bucket messenger-attachments
Тест использует compose.faults.yml, временно включает внедрение ошибок, перезапускает процессы и затем восстанавливает обычную конфигурацию. Во время его выполнения не следует запускать параллельные тесты или ручные загрузки.
Результат успешного выполнения сохраняется в:
results/lab5-level4.json
Если тест был принудительно прерван, обычную конфигурацию можно восстановить явно:
docker compose -f compose.yml -f compose.override.yml up -d --no-build --pull never --scale api=2 --wait --wait-timeout 240
Остановка
Безопасная остановка с сохранением данных:
docker compose down
Намеренное удаление учебных данных, включая persistent volumes:
docker compose down -v
Вторая команда удаляет данные PostgreSQL, Redis, RabbitMQ и MinIO из томов этого Compose-проекта. Для обычной остановки она не используется.
Архитектура и решения
Клиент обращается к двум API-репликам через HAProxy. PostgreSQL хранит пользователей, чаты, сообщения, метаданные вложений, задания и transactional outbox. Redis используется функциональностью, перенесённой из предыдущих работ.
MinIO хранит исходные файлы в staging и готовые результаты обработки. RabbitMQ доставляет задания отдельному worker. Сообщения брокера содержат идентификаторы и параметры задания, но не содержат бинарные данные или credentials.
Что перенесено из лабораторной 4
Перенесены:
- пользователи, авторизация, чаты и сообщения;
- проверки доступа к чатам и вложениям;
- идемпотентное создание сообщений;
- PostgreSQL для метаданных;
- приватное S3-совместимое хранилище;
- проверка MIME по содержимому и ограничений изображения;
- две API-реплики, балансировщик и persistent volumes.
Основное изменение: upload возвращает 202 queued вместо 201 ready. Клиент получает готовность через запрос метаданных. К сообщению можно привязать вложение своего чата в состоянии queued или processing.
Приём файла и transactional outbox
API проверяет файл и сохраняет оригинал в устойчивый staging. Метаданные вложения, задание и запись outbox фиксируются в PostgreSQL одной транзакцией.
Ответ 202 возвращается только после устойчивого сохранения оригинала и успешной фиксации задания.
PostgreSQL является источником истины о состоянии задания и необходимости его публикации. RabbitMQ используется для доставки работы, но не является единственным местом хранения принятого намерения.
Публикация выполняется отдельно. Используются persistent-сообщения, durable-очередь и publisher confirms. Если публикация или запись её подтверждения прерывается, outbox позволяет повторить отправку.
Между S3 и PostgreSQL нет общей распределённой транзакции. При сбое могут остаться неучтённые объекты. Они удаляются механизмом очистки после grace period с проверкой ссылок из метаданных.
Обработка и фиксация результата
Worker получает задание и захватывает его с lease. Доступны состояния:
queued— ожидает обработки;processing— выполняется worker;ready— результаты устойчиво сохранены;failed— постоянная ошибка или исчерпаны попытки.
Worker сохраняет оригинал без изменения байтов и создаёт три варианта:
| Вариант | Формат | Правила |
|---|---|---|
thumbnail |
JPEG | Вписывание в 256×256 без увеличения небольших изображений |
crop |
JPEG | Центральная обрезка до 128×128, увеличение допускается |
optimized |
WebP | Вписывание в 1280×1280 без увеличения |
Для JPEG используется quality 85, для WebP — quality 80 и method 4. Перед преобразованием учитывается EXIF-ориентация. Прозрачность JPEG заменяется белым фоном. Из производных изображений удаляются EXIF, ICC и XMP.
После сохранения объектов worker транзакционно фиксирует метаданные вариантов и состояние ready. ACK отправляется после устойчивой фиксации результата.
При повторной доставке готовой задачи worker проверяет уже сохранённый результат. Новая обработка и второй набор вариантов не создаются.
Повторы и ограничения ресурсов
Постоянные ошибки не повторяются автоматически. Для временных ошибок используется ограниченное число попыток и backoff с jitter.
Настройки решения:
| Параметр | Значение |
|---|---|
| Максимальный размер входного файла | 10 MiB |
| Максимальное число пикселей | 40 млн |
| Обычный бюджет попыток | 3 |
| Конкуренция worker | 1 |
| Prefetch | 1 |
| Таймаут дочернего процесса обработки | 25 секунд |
| Ограничение CPU-времени дочернего процесса | 20 секунд, жёсткий предел 21 секунда |
| Ограничение адресного пространства дочернего процесса | 768 MiB |
| Лимит памяти контейнера worker | 1536 MiB |
| Максимальный Java heap worker | 256 MiB |
| Обычный lease задания | 240 секунд |
Ограничение адресного пространства процесса не является измерением его фактического RSS.
При исчерпании попыток задача получает failed с безопасным error_code. Неуспешные задания остаются в реестре PostgreSQL. Для недопустимых сообщений брокера предусмотрена DLQ.
Явный replay выполняется оператором. Для failed проверяется доступность исходника и сохраняется запись аудита. Replay задачи в ready не запускает повторную обработку.
Очистка staging выполняется после безопасной фиксации результата и истечения grace period. Используемые объекты и исходники активных заданий защищены от удаления.
Переменные конфигурации
Основные переменные .env.example и .env:
| Переменные | Назначение |
|---|---|
COMPOSE_PROJECT_NAME, APP_IMAGE, API_PORT |
Имя проекта, образ приложения, порт балансировщика |
POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD |
PostgreSQL |
REDIS_PASSWORD, SESSION_TTL_SECONDS |
Redis и срок жизни сессии |
API_REPLICAS, API_CPUS, API_MEMORY, DB_POOL_SIZE |
Число API-реплик и ограничения ресурсов |
MINIO_ROOT_USER, MINIO_ROOT_PASSWORD |
Административная учётная запись bootstrap |
S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY |
Приватный bucket и ограниченная учётная запись приложения |
RABBITMQ_USER, RABBITMQ_PASSWORD |
Подключение к брокеру |
JOB_MAX_ATTEMPTS, JOB_TIMEOUT_SECONDS |
Бюджет попыток и длительность lease |
UPLOAD_MAX_CONCURRENT |
Ограничение одновременных upload на API-реплику |
ATTACHMENT_CLEANUP_GRACE_SECONDS |
Защитный интервал перед очисткой |
ATTACHMENT_CLEANUP_INTERVAL_MS, ATTACHMENT_CLEANUP_INITIAL_DELAY_MS |
Расписание очистки |
STAGING_RETENTION_SECONDS |
Срок сохранения исходников неуспешных задач |
WORKER_ENABLED задаётся отдельно для API и worker в Compose.
FAULT_INJECTION_ENABLED отключён в обычной конфигурации и включается только тестовым Compose-файлом. В тестах используются сокращённые lease и grace period; их нельзя выдавать за обычные эксплуатационные настройки.
Доказательства критериев
Указание «вывод терминала» означает наблюдавшийся результат. Такой вывод необходимо сохранить и приложить к репозиторию отдельно; наличие файла лога не предполагается автоматически.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Структура skeleton и локальные ссылки | make check |
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. |
Вывод терминала; отдельный лог пока не приложен |
| Валидность OpenAPI | make validate |
PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested. |
Вывод терминала; отдельный лог пока не приложен |
| Публичный сценарий API | make test |
PASS: lab5 public API scenario; infrastructure and grading evidence remain separate. |
Вывод терминала; отдельный лог пока не приложен |
| Устойчивое принятие задания после ответа upload | level4_check.py, сценарий commit_before_publish |
После реального падения API принятое задание с тем же ID достигло ready |
results/lab5-level4.json |
| Отдельные broker и worker | docker compose ps -a |
RabbitMQ и worker работают отдельными контейнерами | compose.yml, вывод терминала |
| Статусы и готовность вложения | make test, level4_check.py |
Проверены ожидание ready, конечный failed и восстановление через replay |
results/lab5-level4.json, вывод smoke |
| Неизменность оригинала и корректность вариантов | level4_check.py |
Оригинал совпадает побайтно; проверены размеры, MIME, размер файла и SHA-256 вариантов | results/lab5-level4.json |
| Ограниченные повторы | Сценарии permanent_error, transient_error |
Постоянная ошибка завершилась после одной попытки, временная — после трёх | results/lab5-level4.json |
| Worker остановлен, API и брокер перезапущены с сохранением volumes | Отдельный сценарий уровня 3 | В приведённых результатах ещё не подтверждён | Требуется отдельное доказательство |
| Crop 128×128 и optimized WebP | level4_check.py |
Для fixture получены crop 128×128 и WebP 320×200 | results/lab5-level4.json |
| Ориентация, прозрачность, центрирование, повреждённые и огромные изображения | docker compose exec -T worker /opt/images/bin/python /app/selftest.py |
PASS для alpha, small, orientation, centered crop; отклонены broken, bytes_limit, pixels before decode | Вывод selftest; отдельный лог пока не приложен |
| Ограничение времени обработки | Сценарий image_timeout |
Зависший дочерний процесс остановлен; повторная попытка завершилась успешно | results/lab5-level4.json |
| Ограничение памяти worker | Конфигурация контейнера и обработчика | Заданы лимиты контейнера, JVM и дочернего процесса; фактический пик памяти отдельно не измерен | compose.override.yml, infra/images/process_image.py |
| Outbox и crash между COMMIT и publish | Сценарий commit_before_publish |
Принятое задание восстановлено без ручного создания нового | results/lab5-level4.json |
| Backoff с jitter | Сценарий transient_error |
Задержки повторов попали в предусмотренные границы | results/lab5-level4.json |
| Безопасный replay | Сценарии постоянной и временной ошибки | Failed-задача восстановлена; replay готовой задачи не изменил результат | results/lab5-level4.json |
| Падение после записи объектов | Сценарий after_objects |
Объекты существовали до фиксации результата; после восстановления задача завершилась | results/lab5-level4.json |
| Падение перед ACK | Сценарий before_ack |
Повторная доставка подтверждена; ID задания, число попыток и результат не изменились относительно готового состояния до падения | results/lab5-level4.json |
| Восстановление истёкшего lease | Сценарий after_objects |
После остановки worker задание повторно обработано | results/lab5-level4.json |
| Ограничение конкуренции и prefetch | Настройки listener | Concurrency 1 и prefetch 1 | java/src/main/resources/application.yml |
| Безопасная очистка staging | Сценарий after_objects |
Staging и объекты незавершённой попытки удалены; подтверждённые результаты доступны | results/lab5-level4.json |
Эксперименты и отказы
Методика
Проверки выполнялись на локальном стенде Docker Desktop:
- две API-реплики;
- один worker;
- один RabbitMQ;
- PostgreSQL, Redis и MinIO с persistent volumes;
- HAProxy перед API.
Проверялись восстановление принятого задания после падения API, повторная доставка после остановки worker, ограниченные retry, безопасный replay, таймаут обработки и очистка staging.