14 KiB
Отчёт по лабораторной работе 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.
- API потоково принимает PNG/JPEG, ограничивает размер 10 MiB и проверяет тип/размеры заголовка без декодирования полного изображения. Оригинал сначала записывается в RustFS под
staging/. - Затем одной транзакцией PostgreSQL сохраняются метаданные attachment, одна логическая job и запись
job_outbox. Только после успешного COMMIT API возвращает 202. Если БД недоступна после staging, неизвестный объект удаляется планировщиком после безопасного срока. - Отдельный dispatcher читает outbox и помещает в Redis Stream только UUID и служебные поля. Если процесс падает после
XADD, но до отметкиpublished_at, событие может отправиться повторно; это ожидаемая at-least-once семантика. - Отдельный worker читает consumer group, берёт staging-оригинал по доверенному ключу из PostgreSQL, сверяет размер и SHA-256, обрабатывает изображение и пишет результаты в стабильные ключи
attachment_id/pipeline_version/variant. - Только после записи оригинала и всех вариантов 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 остаются одиночными узлами, а производительность не измерялась.
Ответы на вопросы защиты
- Чем publisher confirm отличается от consumer ack? Ответ Redis на
XADDподтверждает приём записи в Stream.XACKподтверждает завершение потребления и вызывается после долговременного эффекта: готовых S3-объектов и COMMIT статусаreadyв PostgreSQL. Это две разные границы. - Что уже сохранено в момент 202? Полный проверенный оригинал уже находится в S3 staging, а PostgreSQL сохранил метаданные, job и намерение отправки через outbox. Событие ещё может ожидать публикации в Stream.
- Почему повторная доставка нормальна и где ключ идемпотентности? Падение между эффектом и ack неизбежно может привести к повтору. Неизменяемый
job_idхранится в PostgreSQL; ключ конечного эффекта —(attachment_id, pipeline_version, variant). Повтор записи по тому же ключу безопасно перезаписывает тот же объект. - Как отличить зависший 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.