Files
mtusi2026lab5/REPORT.md
T

18 KiB
Raw Blame History

Лабораторная 5 — очереди и обработка изображений

Саламатин, БПИ-2304. Целевая оценка — 4, включая минимум на 3. Треки на 5 не выполнялись.

Запуск

Нужны Docker Desktop с Linux containers и Compose. Из каталога лабораторной в PowerShell:

./start.ps1

Скрипт создаёт случайные локальные secrets и .env, собирает API, checks и MinIO, применяет миграции и запускает стенд. Повторный запуск сохраняет пароли. Не менять secrets при сохранённых volumes без процедуры смены пароля. HTTP доступен по http://127.0.0.1:8085. API_PORT меняет порт, API_REPLICAS — число API (по умолчанию 2), MAX_ATTEMPTS — предел попыток (5), SESSION_TTL_SECONDS — срок сессии (3600). APP_ENV и APP_VERSION — метки окружения и версии.

Ручной запуск с Python 3.9+:

python scripts/init_local.py
docker compose build api checks minio
docker compose up -d --no-build --wait --wait-timeout 180

Остановить с сохранением данных: docker compose stop или docker compose down. Команда намеренного удаления учебных данных — docker compose down --volumes; тесты её не вызывают.

Версии закреплены в Dockerfile, requirements.txt и compose.yaml: Python 3.13.15, PostgreSQL 17.6, Redis 7.4.5, HAProxy 3.0.12. MinIO и mc собираются из официальных исходных релизов RELEASE.2025-09-07T16-13-09Z и RELEASE.2025-08-13T08-35-41Z. При первой сборке нужен доступ к реестрам и исходникам; она может занять несколько минут. Собранный ранее локальный MinIO тоже подходит. Минимальная машина — Docker с достаточной памятью для всех контейнеров; проверялось на локальном Docker Desktop.

Что изменилось после lab4

Перенесена собственная lab4: FastAPI, PostgreSQL, scrypt, Redis-сессии с TTL, история с cursor, идемпотентная отправка сообщений, две API-реплики, HAProxy и приватный MinIO. Контракт и публичные tests текущей лабы сохранены.

Раньше API возвращал готовое вложение с кодом 201. Теперь он принимает файл, проверяет его и возвращает 202 queued после устойчивого handoff. Клиент может сразу отправить сообщение с queued-вложением; скачивание до ready отвечает 409. GET метаданных доступен во всех четырёх состояниях. Failed нельзя прикрепить к новому сообщению.

Путь работы: клиент → HAProxy → API → staging MinIO и PostgreSQL jobs → publisher → Redis Streams → worker → конечные объекты MinIO и атомарный результат PostgreSQL. Брокер отделён от Redis сессий, имеет свой volume и AOF с appendfsync always. PostgreSQL, S3, сессии и брокер используют разные именованные volumes. API и worker не публикуют свои порты; снаружи доступен только LB на loopback.

Граница 202 и outbox

API ограничивает тело 10 MiB, принимает его по частям во временный файл, проверяет PNG/JPEG и предел 40 млн пикселей до распаковки. MIME определяется содержимым, filename используется только для отображения. Затем отдельно фиксирует pending-строку, которая учитывает будущий staging key. Под блокировкой этой строки записывает полный оригинал в staging/{attachment_id}, меняет статус на queued и создаёт jobs в одной SQL-транзакции. Ответ 202 формируется из снимка queued и уходит после COMMIT. Временный файл API после запроса не нужен.

Таблица jobs одновременно служит transactional outbox и реестром выполнения. Publisher выбирает готовые к отправке queued-строки через FOR UPDATE SKIP LOCKED, публикует job и отмечает время отправки. До конечного состояния намерение остаётся в PostgreSQL; если задача не захвачена, публикация повторяется раз в 5 секунд. Это сознательно допускает дубли и восстанавливает намерение даже при потере записи в брокере. Уже готовые и failed задания не публикуются.

Разрыв после staging до queued оставляет pending, который cleanup удаляет через час под блокировкой строки. Разрыв после SQL COMMIT до publish не теряет принятую задачу: publisher найдёт ту же jobs-строку после восстановления. Сбой после XADD до SQL COMMIT приведёт к повторной публикации с тем же job_id. Redis Streams с AOF always отвечает после записи AOF. Это граница приёма брокером; она отличается от consumer ack.

Сообщение соответствует contracts/jobs.schema.json: schema_version, job_id, type, attachment_id, pipeline_version=1, attempt и created_at. В нём нет байтов, storage keys, URL, filename и credentials. job_id постоянен при redelivery. БД определяет реальное число попыток; старое значение attempt в дубле не сбрасывает счётчик.

Worker и идемпотентность

Worker читает Streams consumer group по одному сообщению; concurrency=1 и count/prefetch=1. Захват сохраняет processing, номер попытки и lease на 90 секунд. Затем отдельная транзакция держит блокировку jobs-строки на время эффекта. Она не даёт другому worker или восстановителю одновременно опубликовать результат той же работы. После смерти процесса соединение закрывается, а просроченный lease позволяет publisher вернуть задачу в queued. Зависший декодер принудительно завершается по таймауту.

Оригинал копируется из staging в original/{id} без перекодирования. Варианты записываются в variants/{id}/v1/{name}. Ключ эффекта — attachment_id, pipeline_version=1, variant. После всех S3 PUT одна SQL-транзакция публикует variants с размерами и SHA-256 и ставит attachment/job в ready. Только затем отправляется XACK и удаляется запись Streams. Дубль ready — no-op; он не увеличивает attempts и не возвращает объект в processing. При временной ошибке до ack устойчиво фиксируется намерение retry с available_at. При failed — устойчивый реестр ошибки. Если COMMIT не состоялся, ack не выполняется.

Если процесс погиб после S3 PUT до SQL COMMIT, повтор пишет в те же ключи. Сбой после COMMIT результата до ack безопасен: дубль увидит ready. Обещается at least once доставка с идемпотентным эффектом; exactly once доставка не заявляется. Версия pipeline только 1; смена версий относится к невыполненному треку на 5.

Варианты и ограничения

Thumbnail — JPEG quality 85, вписан в 256×256 без увеличения, размеры округляются вниз, минимум 1 px. Для исходника 320×200 получается 256×160. Crop — центрированный квадрат JPEG 128×128, quality 85; маленький исходник можно увеличить. Optimized — WebP quality 80, вписан в 1280×1280 без увеличения. EXIF orientation применяется до расчёта размеров; alpha накладывается на белый. Новое RGB-изображение убирает EXIF, ICC и текстовые метаданные. WebP не обязан быть меньше каждого исходника.

Worker запускает декодирование в отдельном дочернем процессе с таймаутом 30 s. Лимит контейнера — 512 MiB и 1 CPU, одновременно декодируется один файл. Эти ограничения защищают хост, но предельно большие допустимые по пикселям файлы могут не уложиться в память и завершиться failed после ограниченных попыток. API тоже ограничен 512 MiB, одним декодированием на реплику, 10 s ожидания слота, 20 s чтения тела и общим HTTP-бюджетом 35 s. S3 connect/read timeout — 2/3 s.

Постоянный сбой содержимого даёт invalid_image и сразу failed. Ошибка S3 или таймаут обработки временные: backoff min(60, 2^attempt) секунд плюс jitter 0–1 s. Предел по умолчанию 5 попыток, затем retry_exhausted. Зависшая последняя попытка также переходит в failed после lease. Ошибки наружу не содержат SQL, traceback или секреты.

Вместо отдельной DLQ используется jobs + attachments со state/status failed. Оператор видит их в БД. Явный replay:

docker compose exec worker python -m app.pipeline replay JOB_UUID "Причина повторной обработки"

Команда принимает только failed, блокирует строку, создаёт replay_audit и начинает новый ограниченный цикл попыток того же job_id. Ready повторно запустить этой командой нельзя. Staging ready удаляет publisher после безопасного COMMIT; неуспешный исходник хранится 7 дней для replay, затем очищается. Реестр сохраняется, replay после очистки запрещён. Queued/processing очистка не трогает. Неподтверждённые pending очищает отдельный cleanup после часа. Конечные orphan-объекты частично выполненного failed задания автоматически не удаляются; их число ограничено фиксированными ключами.

Проверки и воспроизведение

Полный прогон с Python на хосте:

python scripts/verify.py

На этом компьютере доступен ../.tools/python/python.exe scripts/verify.py. Проверки явно останавливают и перезапускают только контейнеры этого Compose-проекта, сохраняют volumes и восстанавливают API. Не запускать два сценария отказа одновременно.

Отдельные команды:

docker compose run --rm --no-deps checks make check test
docker compose run --rm --no-deps -e PYTHONPATH=/app checks python -m unittest discover -s student-tests -p test_images.py -v
docker compose run --rm --no-deps -e PYTHONPATH=/app checks python student-tests/pipeline_checks.py
docker compose run --rm --no-deps checks sh -ec 'chmod +x scripts/restart.sh; make test-persistence ACTION_SCRIPT=scripts/restart.sh'
docker compose run --rm --no-deps checks sh -ec 'chmod +x scripts/stop-one.sh; make test-failover ACTION_SCRIPT=scripts/stop-one.sh'
docker compose start api

Проверки выполнены 21 ноября 2026 года. Исходный skeleton — 276dbdad8a, ветка solution/bpi-2304-salamatin. Результаты полного прогона — evidence/verification.json, подробности — pipeline.json и текстовые логи. before-restart.json и after-restart.json показывают реальные контейнеры, время старта и сохранённые volumes.

Проверка Что доказывает Файл
Неизменённый публичный smoke 202, ready, авторизация, оригинал и настоящий JPEG thumbnail smoke.txt, smoke-final.txt
Два теста изображения EXIF, белый фон, отсутствие увеличения, удаление metadata images.txt
Worker остановлен, API/broker перезапущены Сообщение с queued-вложением создано, задание сохранено и завершено pipeline.json
API killed между COMMIT и publish при выключенном publisher Outbox доставляет прежнее задание автоматически pipeline.json
Одноразовый os._exit после копирования original Восстановление lease, тот же результат, ровно три объекта вариантов pipeline.json
Три дубля ready-job Attempts и checksums не меняются pipeline.json
Повреждённый staging и replay invalid_image, аудит, восстановление того же job_id pipeline.json
Выключенный MinIO Пять попыток с backoff, итоговый retry_exhausted pipeline.json
Негативные загрузки Размер, повреждение, MIME, filename возвращают 4xx pipeline.json
Persistence и failover Сохранность прежней сессии и данных; работа через оставшуюся API persistence.txt, failover.txt

Для crash после объекта тест создаёт одноразовый /tmp/crash_after_object в worker. Это тестовый fault injection внутри локального контейнера, через HTTP он недоступен. Первый отладочный запуск выявил ошибку тестового окружения: Compose поднимал MinIO как зависимость worker и мешал проверить outage. Исправленный сценарий запускает существующий worker через docker start по ID контейнера. Также удалён лишний запуск нового контейнера из checks, где host bind paths не совпадают. Публичные tests не менялись.

Ограничения

Стенд локальный и учебный: одиночные PostgreSQL, MinIO, брокер, Redis сессий и LB остаются точками отказа. Проверяется restart с сохранением volumes, а не потеря диска или хоста. Нет резервного копирования и TLS для удалённого доступа. При недоступном брокере API может продолжать приём через outbox, пока работают PostgreSQL и staging; недоступный worker не вызывает синхронный resize в API. Readiness API проверяет PostgreSQL, Redis сессий и S3; брокер и worker не критичны для устойчивого приёма. Нет backpressure по длине очереди; оценка предельной нагрузки не проводилась.

Источники и помощь

Задание, контракт и публичные проверки: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab5

Собственная реализация предыдущей работы: ../mtusi2026lab4. Redis Streams: https://redis.io/docs/latest/develop/data-types/streams/ . Pillow: https://pillow.readthedocs.io/en/stable/ . MinIO: https://github.com/minio/minio .

Использованы FastAPI, Psycopg, redis-py, boto3, Pillow и HAProxy. Codex помог написать реализацию, сценарии проверок и пояснения. Разбор для защиты — docs/REVIEW.docx.