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

276 lines
21 KiB
Markdown
Raw 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.
- Commit/PR: solution/khutsaeva-bpi2302
### Подготовка
После клонирования репозитория перейти в его корень.
Создать локальный файл конфигурации:
```powershell
Copy-Item .env.example .env
```
Заполнить в `.env` пароли PostgreSQL, Redis, RabbitMQ, административной учётной записи MinIO и отдельной учётной записи API. Для генерации каждого нового пароля можно использовать:
```powershell
python -c "import secrets; print(secrets.token_hex(24))"
```
Секреты не добавляются в Git и не включаются в отчёт. В `.env.example` должны находиться только примеры и безопасные значения по умолчанию.
Для запуска тестов подготовить Python-окружение:
```powershell
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:
```powershell
docker compose config --quiet
```
Собрать приложение и MinIO:
```powershell
docker compose build api minio
```
Запустить стенд:
```powershell
docker compose up -d --no-build --pull never --scale api=2 --wait --wait-timeout 240
```
При первом запуске предварительно загрузить внешние образы:
```powershell
docker compose pull postgres redis migrate lb rabbitmq
```
Если запуск выполняется впервые, эту команду следует выполнить до `docker compose up`.
Миграции выполняет отдельный сервис `migrate`. Сервис `minio-init` создаёт приватный bucket и настраивает права отдельной учётной записи приложения. Успешное завершение этих двух сервисов со статусом `Exited (0)` является нормальным.
Проверить состояние:
```powershell
docker compose ps -a
curl.exe -i http://localhost:8080/health/ready
```
Основной адрес API — `http://localhost:8080`. Запросы проходят через HAProxy. Прямой доступ к портам API и worker с хоста не требуется.
Если стенд лабораторной 4 использует тот же порт, сначала остановить его из каталога соответствующего проекта.
### Проверки
Проверка обработчика изображений внутри worker:
```powershell
docker compose exec -T worker /opt/images/bin/python /app/selftest.py
```
Публичные проверки:
```powershell
make check
make validate
make test
```
Сценарии отказов уровня 4:
```powershell
python3 -X utf8 tests/level4_check.py --base-url http://localhost:8080 --bucket messenger-attachments
```
Тест использует `compose.faults.yml`, временно включает внедрение ошибок, перезапускает процессы и затем восстанавливает обычную конфигурацию. Во время его выполнения не следует запускать параллельные тесты или ручные загрузки.
Результат успешного выполнения сохраняется в:
```text
results/lab5-level4.json
```
Если тест был принудительно прерван, обычную конфигурацию можно восстановить явно:
```powershell
docker compose -f compose.yml -f compose.override.yml up -d --no-build --pull never --scale api=2 --wait --wait-timeout 240
```
### Остановка
Безопасная остановка с сохранением данных:
```powershell
docker compose down
```
Намеренное удаление учебных данных, включая persistent volumes:
```powershell
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.