Files
mtusi2026lab5/REPORT.md
T

14 KiB
Raw Blame History

Отчёт по лабораторной работе 5 — очереди и обработка изображений

  • Автор / группа: Бадрадин Али / БВТ2302
  • Целевая оценка: 4
  • Трек 5: не заявлен
  • Commit / PR: ещё не опубликованы; текущая версия подготовлена локально
  • Источники: README и контракты лабораторных 4–5; документация FastAPI, SQLAlchemy, Redis Streams, Pillow, boto3 и RustFS. Codex использовался для реализации, ревью и подготовки проверок.

Запуск из чистого клона — Windows PowerShell

Нужны Git, Docker Desktop с запущенным Linux Engine и Python 3.12+. Порт стенда по умолчанию — 8084, чтобы не пересекаться с предыдущими лабораторными.

git clone https://gitea.privcloud.tech/Badradine/mtusi2026lab5.git
Set-Location .\mtusi2026lab5
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt -r requirements-dev.txt
Copy-Item .env.example .env
.\scripts\create-secrets.ps1
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --scale api=2
docker compose --env-file .env ps
Invoke-WebRequest -UseBasicParsing http://localhost:8084/health/ready

Секреты скрипт создаёт только в локальном secrets/; их значения не выводятся и Git их игнорирует. PostgreSQL, Redis для сессий, отдельный Redis Streams broker и RustFS используют постоянные volumes. Сервисы migrate и s3-bootstrap завершаются с кодом 0 после успешной подготовки.

Проверки из PowerShell:

\.venv\Scripts\python.exe scripts/check_contract.py
\.venv\Scripts\python.exe scripts/validate_openapi.py
\.venv\Scripts\python.exe tests/smoke.py --base-url http://localhost:8084
\.venv\Scripts\python.exe student-tests/pipeline_unit.py
\.venv\Scripts\python.exe student-tests/grade4_pipeline.py --base-url http://localhost:8084
\.venv\Scripts\python.exe student-tests/broker_persistence.py --base-url http://localhost:8084
\.venv\Scripts\python.exe student-tests/outbox_recovery.py --base-url http://localhost:8084
\.venv\Scripts\python.exe student-tests/worker_redelivery.py --base-url http://localhost:8084
\.venv\Scripts\python.exe student-tests/replay_failed_job.py --base-url http://localhost:8084
docker compose --env-file .env ps -a

Последние пять сценариев сохраняют краткие результаты в evidence/. Если используется WSL с установленным make, полный набор можно запустить так: make test-grade4 BASE_URL=http://localhost:8084.

Безопасная остановка без удаления учебных данных:

docker compose --env-file .env stop

Только для намеренного полного сброса своей учебной базы, очереди и объектов:

docker compose --env-file .env down -v

Команда down -v удаляет volumes PostgreSQL, Redis, broker и RustFS; перед её запуском сохраните нужные данные.

Архитектура и решения

flowchart LR
  C[Клиент] --> LB[Nginx]
  LB --> API1[API replica 1]
  LB --> API2[API replica 2]
  API1 --> PG[(PostgreSQL)]
  API2 --> PG
  API1 --> S3[(RustFS: staging и готовые объекты)]
  API2 --> S3
  API1 --> R[(Redis: сессии)]
  API2 --> R
  PG --> O[Transactional outbox]
  O --> D[Dispatcher]
  D --> B[(Redis Streams broker)]
  B --> W[Worker]
  W --> S3
  W --> PG

Из Lab 4 сохранены API пользователей, сессий, чатов и сообщений, проверка членства, идемпотентность сообщений, PostgreSQL, приватное S3-хранилище, две API-реплики и балансировщик. Загрузка файла изменилась: вместо синхронной обработки API отвечает 202 Accepted и статусом queued.

  1. API потоково принимает PNG/JPEG, ограничивает размер 10 MiB и проверяет тип/размеры заголовка без декодирования полного изображения. Оригинал сначала записывается в RustFS под staging/.
  2. Затем одной транзакцией PostgreSQL сохраняются метаданные attachment, одна логическая job и запись job_outbox. Только после успешного COMMIT API возвращает 202. Если БД недоступна после staging, неизвестный объект удаляется планировщиком после безопасного срока.
  3. Отдельный dispatcher читает outbox и помещает в Redis Stream только UUID и служебные поля. Если процесс падает после XADD, но до отметки published_at, событие может отправиться повторно; это ожидаемая at-least-once семантика.
  4. Отдельный worker читает consumer group, берёт staging-оригинал по доверенному ключу из PostgreSQL, сверяет размер и SHA-256, обрабатывает изображение и пишет результаты в стабильные ключи attachment_id/pipeline_version/variant.
  5. Только после записи оригинала и всех вариантов worker транзакционно ставит ready/succeeded, удаляет staging и делает XACK. Если он падает до ack, повторная доставка видит завершённую job, не меняет готовый результат и подтверждает старое сообщение.

Redis для пользовательских сессий и Redis Streams broker запущены отдельными сервисами и имеют отдельные пароли и volumes. Оба используют AOF appendfsync everysec. PostgreSQL является источником истины для состояния job и outbox; Stream — устойчивый транспорт/сигнал для worker.

Pipeline v1 создаёт:

  • thumbnail: JPEG, вписывание в 256×256 без увеличения, quality 85;
  • crop: JPEG 128×128, quality 85;
  • optimized: WebP, максимальная сторона 1280 px, quality 82, method 4.

Картинка ориентируется по EXIF, а EXIF не переносится в производные изображения. Worker обрабатывает по одному заданию за процесс, ограничен 768 MiB памяти и дедлайном 60 секунд; lease — 180 секунд, максимум — 5 попыток. Временные ошибки получают ограниченный exponential backoff с jitter. Постоянные ошибки переводят job во failed; явный replay разрешён только если исходник ещё хранится в staging и создаёт audit-запись.

Результаты проверок

Критерий Команда / сценарий Наблюдение на момент подготовки отчёта Доказательство
Структура, ссылки и синтаксис python scripts/check_contract.py PASS; проверены контракты и синтаксис Python evidence/static-checks.txt
OpenAPI 3.1 / JSON Schema python scripts/validate_openapi.py PASS evidence/static-checks.txt
Python-компиляция всех source/tests python -m compileall -q src scripts tests student-tests PASS, код завершения 0 evidence/static-checks.txt
Compose-конфигурация и локальные secret paths docker compose --env-file .env config --quiet PASS evidence/static-checks.txt
Локальный image pipeline probe синтетический JPEG 640×480 с EXIF PASS: JPEG 256×192, JPEG 128×128, WebP 640×480 evidence/static-checks.txt
Публичный API smoke python tests/smoke.py --base-url http://localhost:8084 PASS: lab5 public API scenario evidence/test.log
Лимиты и все варианты python student-tests/grade4_pipeline.py --base-url http://localhost:8084 PASS: queued → ready; три варианта и исходник проверены; corrupt/MIME 415, pixel/byte limits 413 evidence/grade4-pipeline.json
Сохранность Redis Stream python student-tests/broker_persistence.py --base-url http://localhost:8084 PASS: stream entry пережила restart broker с volume; тот же attachment завершён worker-ом evidence/broker-persistence.json
API restart + crash dispatcher до XADD python student-tests/outbox_recovery.py --base-url http://localhost:8084 PASS: queued job/outbox пережили restart API; dispatcher crash exit 75 до XADD; тот же attachment восстановлен до ready evidence/outbox-recovery.json
Worker crash после COMMIT до XACK python student-tests/worker_redelivery.py --base-url http://localhost:8084 PASS: crash exit 75 после side effect; redelivery завершилась exit 0; варианты неизменны, XACK после COMMIT evidence/worker-redelivery.json
Failed registry и безопасный replay python student-tests/replay_failed_job.py --base-url http://localhost:8084 PASS: явный replay перевёл failed → ready; записан audit, исходник сохранён до готовности evidence/replay-failed-job.json

Стенд Compose запущен локально. Публичный smoke и все пять сценариев уровня 4 завершились PASS; фактические выводы и JSON-доказательства сохранены в evidence/. Проверка контракта (python scripts/check_contract.py), OpenAPI и Python-компиляции также завершились PASS. make как команда в текущем Windows-окружении не запускалась из-за ошибки системной DLL; эквивалентные скрипты запускались напрямую.

Ограничения и известные ошибки

  • Redis Streams и RustFS размещены на одиночных локальных узлах; Compose не создаёт HA-кластер и не доказывает сохранность при потере диска или всего хоста.
  • AOF everysec может потерять последнюю секунду записей при аварийном отключении питания. Outbox повторно публикует незавершённые задания, но сам PostgreSQL и его диск остаются отдельной границей отказа.
  • Ограничение worker — один job одновременно на контейнер; throughput не измерялся и трек на оценку 5 не заявлен.
  • Текущие сценарии подтверждены на локальном Compose-стенде; Redis Streams и RustFS остаются одиночными узлами, а производительность не измерялась.

Ответы на вопросы защиты

  1. Чем publisher confirm отличается от consumer ack? Ответ Redis на XADD подтверждает приём записи в Stream. XACK подтверждает завершение потребления и вызывается после долговременного эффекта: готовых S3-объектов и COMMIT статуса ready в PostgreSQL. Это две разные границы.
  2. Что уже сохранено в момент 202? Полный проверенный оригинал уже находится в S3 staging, а PostgreSQL сохранил метаданные, job и намерение отправки через outbox. Событие ещё может ожидать публикации в Stream.
  3. Почему повторная доставка нормальна и где ключ идемпотентности? Падение между эффектом и ack неизбежно может привести к повтору. Неизменяемый job_id хранится в PostgreSQL; ключ конечного эффекта — (attachment_id, pipeline_version, variant). Повтор записи по тому же ключу безопасно перезаписывает тот же объект.
  4. Как отличить зависший worker от долгой обработки и не запустить два неконтролируемых дубля? У обработки есть дедлайн 60 секунд и lease 180 секунд. Истёкший lease возвращает job в очередь; блокировка строки и сверка номера попытки не дают старой попытке изменить актуальное состояние. Повторные сообщения при ready становятся no-op с ack.

Чек-лист перед отправкой PR

  • Публичный make test / tests/smoke.py завершился PASS на работающем Docker-стенде.
  • Все четыре end-to-end проверки уровня 4 завершились PASS; JSON-файлы сохранены в evidence/.
  • Проверено состояние всех сервисов: API×2, PostgreSQL, Redis sessions, broker, worker, dispatcher, RustFS и LB.
  • Проверены git status, секреты и фактические результаты; в отчёт добавлен commit/PR.