Files
mtusi2026lab5/REPORT.md
T
2026-11-11 23:05:16 +03:00

21 KiB
Raw Blame History

Отчёт — лабораторная 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.