Лабораторная 5. Очереди и асинхронная обработка изображений
Отделить приём файла от тяжёлой обработки, корректно переживать повторную доставку и остановку worker.
Это skeleton, а не готовый сервер. Здесь есть задание, контракт и публичные проверки. Реализацию приложения, Dockerfile и требуемую инфраструктуру пишет студент. Язык и framework свободные; UI не обязателен.
Карта курса · Процесс fork/PR · OpenAPI · Семантика API · Проверки · Отчёт · Примеры JSON · Памятка преподавателю
Откуда начинаем
Нужен минимум lab4. POST upload теперь возвращает 202 queued, а готовность выясняется через метаданные. В HTTP upload клиент по-прежнему передаёт все байты.
Архитектура: API → устойчивый staging + запись задания → брокер → worker → конечный S3 + PostgreSQL. Клиент опрашивает статус.
Что сделать
- Выберите RabbitMQ, Redis/Valkey Streams, NATS JetStream или другой брокер с persistence и подтверждениями. Обычный Pub/Sub без хранения не подходит.
- Разделите приём, durable staging, публикацию задания, обработку и фиксацию результата. Прочитайте contracts/attachment-states.md.
- Реализуйте worker отдельно от API: публикация оригинала в конечный S3-prefix и thumbnail 256×256 по правилам контракта.
- Добавьте конечные состояния, ограниченные повторы и идемпотентную запись результатов. Не помещайте bytes или credentials в сообщения брокера.
- Остановите worker, загрузите файл, перезапустите API/worker, убедитесь в завершении принятой задачи. Затем проверьте повторную доставку.
Оценка «3»: работающий минимум
- Весь минимум lab4 сохранён с переходом upload 201 → 202. API возвращает 202 только после устойчивого приёма оригинала и сохранения задания; остановка API после ответа не теряет работу.
- В общем Compose/Swarm есть отдельные broker и worker. Сообщения durable, доставка at least once, подтверждение только после устойчивого эффекта. Недоступность worker не заставляет API выполнять resize синхронно.
- Состояния queued/processing/ready/failed доступны в API. Worker сохраняет оригинал и один thumbnail; original неизменен, thumbnail соответствует контракту. Публичный smoke проходит.
- Есть ограниченный retry (конкретное число попыток в конфигурации, например 5), финальное failed с безопасным error_code. Повтор одной job не создаёт второго набора вариантов.
- Демонстрация: worker остановлен → upload 202 → сообщение с вложением создано → API перезапущен → worker запущен → ready и доступный thumbnail. Принятое задание не исчезает при рестарте broker с volume.
Оценка «4»: уровень стажёра/джуна
Весь уровень 3 и все пункты ниже:
- Добавлены crop 128×128 и optimized WebP по контракту, параметры качества/удаления метаданных описаны. Невалидные/огромные изображения ограничены по bytes, пикселям, времени и памяти worker.
- Разрыв между PostgreSQL и broker закрыт transactional outbox или другой доказанной схемой восстановления намерения. Внедрён crash между COMMIT и publish; после восстановления задача доходит до ready без ручного создания нового задания.
- Retry использует backoff с jitter, различает постоянные/временные ошибки; есть DLQ/реестр failed и безопасный явный replay. «Повторить» не означает безусловно исполнить дубль уже успешной job.
- Проверена остановка worker после записи объекта, но до ack; повтор завершает тот же результат. Есть timeout/lease для зависшего processing, ограниченная конкуренция/prefetch и очистка staging после безопасной фиксации.
В этой реализации pipeline v1 создаёт thumbnail JPEG с quality=85 и вписыванием без увеличения, crop JPEG 128×128 с quality=85 и оптимизированный WebP с quality=82, method=4, максимальной стороной 1280 px. EXIF не переносится. API ограничивает upload до 10 MiB и проверяет заголовок/размер изображения до декодирования; worker допускает до 40 млн пикселей, работает с дедлайном 60 секунд, одним заданием за раз и лимитом памяти контейнера 768 MiB. Lease равен 180 секундам, число попыток — 5; временные ошибки получают экспоненциальную задержку с jitter.
Оценка «5»: исследование и доказанный результат
Весь уровень 4 и один законченный трек на выбор. Приведите гипотезу, повторяемую методику, результаты и ограничения.
Трек 1. Очередь под перегрузкой. Сравните ≥3 настройки concurrency/prefetch на разных размерах изображений. Измерьте throughput, queue lag, p95 времени до ready и RSS; покажите backpressure и ограничение количества принятой работы. Докажите восстановление после перегрузки, объясните компромисс latency/ресурсы.
Трек 2. Доказанная идемпотентность pipeline. Постройте versioned pipeline и автоматический fault-injection для дубля, reorder, crash до/после side effect и устаревшей job после новой версии. Зафиксируйте инварианты, покажите отсутствие потери подтверждённых задач и перезаписи нового результата старым. Обсудите почему это не exactly-once доставка.
Как начать и проверить
# Работает прямо в skeleton, Python 3.9+; приложение не запускается:
make check
# После реализации запустите свой сервер/стенд по REPORT.md.
# Для Lab 5 внешний порт по умолчанию — http://localhost:8084, чтобы не конфликтовать с предыдущими лабораторными.
make test
.env.example, compose.example.yaml и contracts/infrastructure.json описывают настройки и роли компонентов. compose.example.yaml — список ролей с пустым services, не запускаемый стенд. Реализуйте свой compose.yaml/stack.yaml, закрепите версии образов, заполните локальный .env и опишите bootstrap/миграции. Все зависимости поднимаются из этого репозитория; ссылка «у меня БД уже установлена» не заменяет воспроизводимость.
# Compose-вариант после реализации:
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# Дождитесь /health/ready; затем make test.
# Для Swarm укажите эквивалентные build/push/deploy-команды в REPORT.md.
Примеры запросов доступны в examples/requests.http, примеры JSON — в contracts/examples.json. Для полной проверки схемы (по желанию локально; CI делает её автоматически):
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt -r requirements-dev.txt
make validate PYTHON=.venv/bin/python
Smoke не выставляет оценку автоматически. Проверку сохранности/отказов запускайте явно по tests/README.md, остальные доказательства приведите в отчёте.
Для объявленного уровня 4 после запуска Compose используйте дополнительные сценарии:
make test-grade4 BASE_URL=http://localhost:8084
Они проверяют оригинал и три варианта изображения, лимиты входа, сохранность записи Stream после рестарта broker с volume, crash dispatcher до XADD после подтверждённого API COMMIT, восстановление через outbox после перезапуска API, повторную доставку после фиксации результата до XACK и явный безопасный replay задания из failed. Сводки записываются в evidence/; эти сценарии создают постоянные синтетические данные, как и публичный smoke.
Сценарий защиты
- Запустить make test: API возвращает 202, GET доходит до ready, оригинал и настоящий JPEG thumbnail проверяются.
- Остановить worker своим скриптом, загрузить файл, убедиться, что content отвечает 409, а другие сообщения продолжают работать.
- Перезапустить API/broker с сохранением volumes, запустить worker; та же запись должна стать ready. Зафиксировать порядок действий и ID без токенов.
- Для 4: воспроизвести crash после side effect до ack, разрыв COMMIT/publish и replay failed; для 5 — выбранный эксперимент.
Что должно быть в PR
Worker, брокер в общем стенде, схема jobs, migrations/outbox по уровню, конфигурация retry, тесты сбоев и отчёт.
Заполните REPORT.md и шаблон PR, укажите целевую оценку/трек. Не меняйте обязательный контракт и публичные tests ради зелёного результата. Сохраняйте возможности предыдущих лабораторных в пределах объявленных переходов.
Вопросы на защите
- Чем publisher confirm отличается от consumer ack?
- Что именно уже сохранено в момент 202?
- Почему повторная доставка нормальна и где находится ключ идемпотентности job?
- Как отличить зависший worker от долго работающего и не запустить два неконтролируемых дубля?
Краткие ответы применительно к этому стенду:
- Publisher confirm и consumer ack — это разные подтверждения. Ответ Redis на
XADDозначает, что Stream принял событие;XACKвызывается worker только после сохранения оригинала и вариантов, а также фиксацииready/succeededв PostgreSQL. Redis работает с AOFappendfsync everysec; при потере последней записи outbox повторно публикует незавершённую работу. - К моменту ответа 202 исходный файл уже находится в S3 staging, а PostgreSQL одной транзакцией сохранил метаданные вложения, job и outbox. Само событие может ещё не быть в Redis Stream — dispatcher прочитает outbox позже.
- Повторная доставка ожидаема при падении между записью результата и ack или между Redis
XADDи отметкой outbox. Неизменяемыйjob_idхранится в PostgreSQL; попытка увеличивается при новом retry. Эффекты адресуются детерминированными ключами(attachment_id, pipeline_version, variant), поэтому повтор не создаёт второй набор объектов. - Зависание ограничивается дедлайном и lease. Worker выполняет по одному заданию; дедлайн 60 секунд меньше lease 180 секунд. Dispatcher возвращает истёкший lease в очередь. Захват и изменение состояния блокируются в PostgreSQL, а
attemptотсекает устаревшее завершение. Повтор послеreadyтолько подтверждает старое событие и не меняет результат.