19 KiB
Лабораторная 5. Очереди и асинхронная обработка изображений
Автор: Каменский Андрей, БПИ2301. Целевая оценка: 4. Трек на 5 не заявлен. Реализация продолжает собственный мессенджер lab1–4. Commit/PR в рамках этой работы не публиковались.
Запуск из чистого clone
Нужны Docker/Compose v2 и интернет для первой сборки MinIO из закреплённого commit. Приложение использует Python 3.13.0, PostgreSQL 16.6, Redis 7.4.2, HAProxy 3.0.12, MinIO RELEASE.2025-10-15T17-29-55Z. Версии Python-библиотек зафиксированы в requirements.txt; обработка — Pillow 13.0.0.
python3 scripts/setup-env.py # только если .env отсутствует
# Скрипт создаёт случайные пароли, права 0600; секреты не печатает.
docker compose config --quiet
docker compose up -d --build --wait
python3 tests/smoke.py
Автоматически выполняются миграции до 009, создание bucket, пользователей и S3-политик. Для старого стенда сохраняются прежние .env/volumes. Отдельные действия оператора: создать .env при первом запуске, обеспечить Docker ресурсы и дождаться сборки/healthchecks. БД, S3 или broker вне репозитория не требуются.
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt -r requirements-dev.txt
make verify-lab5 PYTHON=.venv/bin/python
Полная проверка создаёт собственный UUID-проект на свободном порту, новые пароли
и пустые volumes. После проверки удаляется только этот тестовый проект.
Результаты сохраняются в evidence/lab5-summary.json и связанных текстовых логах.
Обычный останов: docker compose down (volumes остаются).
Намеренное удаление учебных данных выбранного проекта:
docker compose down --volumes (не является частью обычного запуска).
Архитектура и транзакционные границы
API × 2 → staging MinIO + PostgreSQL job/outbox → dispatcher → отдельный Redis Streams broker → worker → originals/ + variants/ MinIO → COMMIT ready. HAProxy распределяет HTTP между API. Redis сессий отделён от Redis очереди. PostgreSQL — источник истины для задания, попыток, состояния, результатов и audit. MinIO — источник сохранённых байтов. API и worker не требуют локального постоянного диска: временные файлы используются только в пределах операции.
- До PUT отдельно коммитится UploadIntent pending, как в lab4. Advisory lock на staging-ключ защищает загрузку от преждевременной очистки.
- После полного приёма, проверки и S3 PUT одной транзакцией сохраняются Attachment queued, AttachmentJob и committed-состояние UploadIntent.
- Только после этого COMMIT возвращается 202 queued. Ответ не зависит от готовности worker и не утверждает, что broker уже принял сообщение.
- Job одновременно служит outbox. Dispatcher выбирает queued с published_at=NULL и наступившим next_run_at, делает XADD, затем коммитит published_at.
- Worker сохраняет processing/lease, затем блокирует строку job на время ограниченной попытки. После записи всех четырёх объектов атомарно сохраняет варианты, ready и снятие lease.
- XACK и XDEL выполняются одной Redis-транзакцией после DB COMMIT. При retry до ACK фиксируется новое намерение публикации, при failed — конечный результат.
Успех XADD при AOF appendfsync=always означает принятие брокером. XACK означает, что consumer уже сохранил устойчивый результат либо retry/failed. Это разные границы. При потере ответа XADD публикация повторяется, поэтому доставка at least once, а не exactly once. В Stream не помещаются bytes, credentials или клиентские пути; envelope соответствует contracts/jobs.schema.json. Ключ исходника worker читает из доверенной записи БД, не из произвольного URL сообщения.
Все прежние возможности сохранены в пределах перехода 201 ready → 202 queued: сессии с TTL, ACL, два API, идемпотентность сообщений, история, лимиты файлов и побайтный оригинал. Queued/processing разрешено прикреплять к сообщению; failed — 409. Content для любого неготового вложения — 409. Чужие вложения/варианты — 404.
Миграция 009 сохраняет старые ID/связи и добавляет job для каждого старого вложения. Его прежний original используется как staging-источник. Очистка учитывает совпадение staging/final key и не удаляет старый оригинал.
Преобразования и ограничения
Все производные версии создаются независимо из исходника после EXIF orientation. Новый RGB canvas не наследует EXIF/XMP/ICC. Alpha компонуется на белый фон. Оригинал никогда не перекодируется, его размер и SHA-256 проверяются worker.
| Вариант | Параметры |
|---|---|
| thumbnail | JPEG, quality=85, optimize=True, вписать в 256×256 без увеличения |
| crop | JPEG, quality=85, optimize=True, центральный квадрат 128×128 |
| optimized | WebP, quality=80, method=4, вписать в 1280×1280 без увеличения |
Вписывание использует целочисленное округление вниз и минимум 1 px. Crop может увеличивать маленький исходник. Не заявляется уменьшение каждого WebP относительно оригинала. Формат, размеры и SHA-256 вариантов находятся в публичных метаданных, ключи S3 там отсутствуют. Скачивание идёт через API без redirect.
Лимит HTTP — 10 MiB, декодированных пикселей — 40 млн. Проверки размера/формата сохранены в API и повторяются при обработке. Дочерний Linux-процесс Pillow имеет RLIMIT_AS=768 MiB и CPU limit; parent завершает и дожидается его по wall timeout 30 с. Worker-контейнер ограничен 1 GiB, 1 CPU, tmpfs 128 MiB. S3-вызовы имеют ограничения connect/read (5 с); timeout обработки относится к преобразованию, а не к полной HTTP-загрузке или всей очереди.
Повторы, конкурентность, восстановление и retention
По умолчанию один consumer, prefetch=1. WORKER_CONCURRENCY задаёт число consumers; каждый берёт по одному сообщению. После ошибки временного класса применяется backoff с jitter: U(cap/2, cap), cap=min(60 с, 2 с × 2^(cycle_attempt−1)). Максимум JOB_MAX_ATTEMPTS=5 на цикл. Ошибки формата/checksum/ресурсов постоянные; ошибки доступности и wall timeout временные. Клиент видит безопасный error_code, при исчерпании попыток — retry_exhausted. Бесконечного retry обработки нет. Публикация durable outbox при недоступном broker повторяется до восстановления.
Lease по умолчанию 120 с. Dispatcher восстанавливает истёкшее processing через SELECT FOR UPDATE SKIP LOCKED. Живая попытка удерживает строку на время обработки; это исключает одновременную публикацию двумя попытками. После crash DB lock освобождается, lease позволяет запустить восстановление. Простая redelivery не увеличивает attempt. Управляемый retry/replay увеличивает его, сохраняя job_id.
Ключ эффекта: (attachment_id, pipeline_version=1, variant). Конечные S3-ключи детерминированы. Дубль ready проверяет наличие/размер зафиксированных объектов и подтверждается без повторной обработки. Поддержка разных pipeline_version и эксперимент с устаревшей версией относятся к треку 5 и здесь не заявлены.
Реестр failed — таблица attachment_jobs, CLI src.pipeline.admin failed.
Replay допускает только failed с существующим staging, требует operator/reason,
пишет job_replays и запускает новый ограниченный цикл. Ready отклоняется.
Задание и аудит сохраняются после очистки staging.
Ready staging удаляется после COMMIT результата; failed — после семи дней. Очистка блокирует Attachment так же, как replay, и повторяется при ошибках S3. Queued/processing не удаляются по возрасту. Незавершённый staging без задания обслуживается по durable UploadIntent после grace=300 с; действующая загрузка защищена advisory lock. Reconciler lab4 продолжает контролировать originals/, но не отмечает queued/processing как missing.
Доказательства критериев
Полный повтор: make verify-lab5 PYTHON=.venv/bin/python.
В tests/lab5.py fault hooks включаются только на явном изолированном стенде;
в обычной конфигурации PIPELINE_FAULT_INJECTION=false. Код ошибки 81/82/83/84
соответствует реальному аварийному завершению dispatcher/worker через os._exit,
а не симуляции успешного HTTP-ответа.
| Критерий | Проверка / наблюдение | Доказательство |
|---|---|---|
| Контракт и качество | lint, offline check, OpenAPI/JSON Schema | lab5-quality.txt |
| Чистый запуск | Новый Compose project, новые credentials и пустые volumes | lab5-clean-start.txt |
| Публичный минимум | Неизменённый course-tests/smoke.py lab5: 202, ready, настоящий JPEG и оригинал | lab5-public-smoke.txt |
| Предыдущие возможности | PNG/JPEG, ACL, лимиты, вложения и 16 повторов через две API-реплики | lab5-regression.txt |
| Переход с lab4 | Настоящая БД 008 → 009, прежний original неизменен, созданы 3 варианта | lab5-migration.txt |
| Лимиты worker | Реальное отклонение повреждённых/огромных по пикселям изображений и ограничение памяти subprocess | lab5-limits.txt |
| Геометрия и форматы | 320×200 → 256×160; 1001×667 → 256×170; маленькое не увеличивается; crop, WebP, EXIF, alpha | lab5-faults.txt |
| Worker остановлен | 202, queued прикрепляется к сообщению, content 409, сообщения работают | lab5-faults.txt |
| API/broker restart | После restart с volumes тот же ID и оригинал доходят до ready | lab5-faults.txt |
| Broker недоступен | API принимает файл; job остаётся в outbox и выполняется после восстановления | lab5-faults.txt |
| COMMIT/publish | Exit 81 до XADD; после восстановления прежняя job ready | lab5-faults.txt |
| Потеря подтверждения публикации | Exit 82 после XADD до COMMIT флага; повтор безопасен | lab5-faults.txt |
| S3 side effect до COMMIT/ACK | Exit 83, processing/неподтверждённая доставка; восстановление в те же четыре объекта | lab5-faults.txt |
| COMMIT результата до ACK | Exit 84; redelivery подтверждает готовый результат без новой попытки | lab5-faults.txt |
| Дубли | Два дубля ready не меняют attempt и набор/ETag объектов | lab5-faults.txt |
| Retry/failed/replay | Временная ошибка исчерпывает 3 тестовые попытки, постоянная завершается на первой; replay с audit; ready replay отвергнут | lab5-faults.txt |
| Wall timeout | Задержанный дочерний decoder завершается parent, исчерпывает ограниченные попытки; replay после снятия сбоя успешен | lab5-faults.txt |
| Staging cleanup | Ready удаляется после COMMIT, failed хранится до retention, после очистки replay отклоняется; orphan очищается, queued защищён | lab5-faults.txt |
| Сохранность | Прежняя сессия и файл после restart API и всех хранилищ, включая broker | lab5-persistence.txt |
| Failover | Остановлена именно принявшая файл API-реплика, другая возвращает прежние байты | lab5-failover.txt |
| Регрессии замечаний | 40 MP, MIME/PNG, filename, pause PostgreSQL после начала SQL, восстановление | lab5-review.txt |
| Итоговый smoke | Повтор после всех отказов | lab5-final-smoke.txt |
Имена файлов в таблице находятся в evidence/. Машинная сводка — evidence/lab5-summary.json. Fault-стенд использует lease=5 с, max_attempts=3, backoff base=0.5 с/cap=2 с и decoder timeout=1 с, чтобы сценарии были короткими; после завершения обычная конфигурация восстановлена.
Ограничения
Это локальный учебный стенд с синтетическими данными. Broker, PostgreSQL, MinIO, HAProxy и host не реплицируются и остаются точками отказа. AOF/volumes защищают от проверенных рестартов, но не от физической потери диска или всех копий данных. Нет backup-restore и обещания восстановления произвольно удалённых объектов.
Во время обработки удерживается DB row lock и соединение; это сознательное упрощение для ограниченной конкуренции, не доказательство масштабирования. Результаты действительны для pipeline_version=1 с неизменными правилами кодирования. Дубликат ready проверяет наличие и размеры, не перечитывает все байты для SHA-256; от произвольной порчи объекта тем же размером эта проверка не защищает.
Нет глобального лимита числа принятых jobs и исследования очереди под перегрузкой. В broker действует noeviction: при заполнении outbox сохраняется в БД до освобождения места. Нет публичного HTTP replay; CLI предназначен для оператора с доступом к стенду. После истечения retention для failed исходник повторно обработать нельзя. В репозиторий включены только актуальные проверки lab5 и регрессии обязательных возможностей предыдущих работ. Полная приёмка — verify-lab5.
Источники и помощь
Задание и contracts взяты из предоставленного skeleton mtusi2026lab5. Публичные course-tests скопированы без ослабления проверок. Собственные тесты lab4 адаптированы только к объявленному переходу на 202 и ожиданию ready. Использован Codex для реализации, ревью кода, тестов и подготовки документации.
- Redis Streams: https://redis.io/docs/latest/develop/data-types/streams/
- XAUTOCLAIM: https://redis.io/docs/latest/commands/xautoclaim/
- Redis persistence: https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/
- Pillow ImageOps: https://pillow.readthedocs.io/en/stable/reference/ImageOps.html
- Pillow WebP: https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html#webp