forked from mtusi2026/mtusi2026lab5
206 lines
19 KiB
Markdown
206 lines
19 KiB
Markdown
# Лабораторная 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.
|
||
|
||
```sh
|
||
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 вне репозитория не требуются.
|
||
|
||
```sh
|
||
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 для реализации, ревью кода, тестов и подготовки документации.
|
||
|
||
- 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
|