forked from mtusi2026/mtusi2026lab5
276 lines
21 KiB
Markdown
276 lines
21 KiB
Markdown
# Отчёт — лабораторная 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. |