Files
2026-11-17 17:53:23 +03:00

19 KiB
Raw Permalink Blame History

Лабораторная 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 не требуют локального постоянного диска: временные файлы используются только в пределах операции.

  1. До PUT отдельно коммитится UploadIntent pending, как в lab4. Advisory lock на staging-ключ защищает загрузку от преждевременной очистки.
  2. После полного приёма, проверки и S3 PUT одной транзакцией сохраняются Attachment queued, AttachmentJob и committed-состояние UploadIntent.
  3. Только после этого COMMIT возвращается 202 queued. Ответ не зависит от готовности worker и не утверждает, что broker уже принял сообщение.
  4. Job одновременно служит outbox. Dispatcher выбирает queued с published_at=NULL и наступившим next_run_at, делает XADD, затем коммитит published_at.
  5. Worker сохраняет processing/lease, затем блокирует строку job на время ограниченной попытки. После записи всех четырёх объектов атомарно сохраняет варианты, ready и снятие lease.
  6. 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 для реализации, ревью кода, тестов и подготовки документации.