10 KiB
Lab5: объяснение реализации и подготовка к защите
Автор: Каменский Андрей, БПИ2301.
Что добавлено к четвёртой работе
Раньше API принимал файл, сохранял оригинал и отвечал 201 ready. Теперь API сначала надёжно принимает исходник, записывает работу и отвечает 202 queued. Отдельный worker готовит версии изображения. У пользователя остаётся одно вложение с одним ID; thumbnail нужен для превью, crop — для квадратного показа, optimized — для показа большого изображения с ограниченным разрешением.
Пример для 4000×3000: оригинал 4000×3000, thumbnail 256×192, crop 128×128, optimized WebP 1280×960. Оригинал остаётся побайтно прежним.
Какие процессы запускаются
| Процесс | Что делает |
|---|---|
| API × 2 | Пользователи, чаты, сообщения, приём и чтение вложений |
| PostgreSQL | Источник истины для вложений, jobs/outbox, попыток и результатов |
| Redis | Сессии и кэш предыдущих работ |
| Broker: отдельный Redis | Хранит Stream очереди и неподтверждённые доставки |
| Dispatcher | Отправляет outbox, восстанавливает истёкшие lease, очищает staging |
| Worker | Читает Stream и выполняет обработку |
| MinIO | Сохраняет staging, исходные изображения и варианты |
| Reconciler | Сохраняет прежнюю сверку originals/ с БД, пропускает незавершённую обработку |
| Migration / bootstrap | Подготавливают БД, bucket и S3-политики |
Pillow делает преобразования в дочернем процессе worker. Redis Streams работает как очередь с consumer group, а не как обычный Pub/Sub. Дополнительный RabbitMQ для этого решения не требуется.
Что уже гарантировано в момент 202
- Клиент передал все байты, прошли базовые проверки.
- В MinIO надёжно сохранён полный исходник в staging/.
- В одной транзакции PostgreSQL сохранены Attachment и AttachmentJob.
- Эта job является также записью outbox: published_at=NULL означает, что её ещё требуется отправить в брокер.
Ответ не обещает, что сообщение уже находится в брокере или варианты готовы. Если broker не работает, dispatcher продолжает попытки публикации. API readiness зависит от PostgreSQL, Redis-сессий и MinIO, но не от worker/broker.
Зачем outbox
Обычная последовательность «COMMIT в БД → отправить в очередь» имеет разрыв: процесс может умереть между действиями. У нас намерение отправки — сама job, сохранённая вместе с вложением. Dispatcher найдёт её после восстановления.
XADD выполняется перед фиксацией published_at. Если broker сохранил сообщение, а dispatcher умер до COMMIT, сообщение будет отправлено повторно. Это допустимо: потеря исключается за счёт сохранённого намерения, а дубли обрабатывает worker. Redis настроен с AOF, appendfsync=always, persistent volume и noeviction.
Как переживаем повторную доставку и падение worker
job_id обозначает одну логическую работу и сохраняется при повторе доставки. Управляемый retry увеличивает attempt, простая redelivery этого не делает. Итоговый ключ эффекта — attachment_id + pipeline_version=1 + variant. В S3 используются детерминированные ключи: повтор не создаёт новый набор файлов.
Worker фиксирует processing и lease, затем удерживает блокировку строки job на время ограниченной обработки и публикации результата. Конкурирующий consumer пропускает занятую строку. Dispatcher восстанавливает только истёкшие processing, которые не удерживаются живой попыткой. Crash освобождает блокировку; следующая попытка использует тот же исходник и те же конечные ключи.
После ready повтор проверяет наличие/размер уже зафиксированных объектов и подтверждает доставку без повторной обработки. Нельзя вернуть ready в processing. ACK и удаление записи Stream выполняются одной Redis-транзакцией после DB COMMIT. Это at least once + идемпотентный эффект, а не exactly-once доставка.
Ошибки, повторы и очистка
Временная ошибка S3/обработки приводит к retry. Задержка: случайное значение между половиной и полным значением min(cap, base × 2^(номер_попытки−1)). По умолчанию base=2 с, cap=60 с, максимум 5 попыток на цикл. Повреждённый исходник, несовпадение checksum и превышение ресурсов завершаются без бессмысленных повторов. Исчерпание временных попыток даёт retry_exhausted.
Реестр failed хранится в PostgreSQL и доступен через CLI. Replay принимает только failed с ещё доступным staging и требует operator/reason для аудита. Это новый ограниченный цикл, а не безусловное выполнение успешного дубля.
После ready staging удаляется отдельным проходом. Между COMMIT ready и удалением может быть задержка; ошибка удаления повторяется. Активные queued/processing никогда не удаляются по возрасту. Failed хранится семь дней. Незавершённые загрузки без задания удаляются по журналу pending после grace (по умолчанию 300 с) с той же advisory lock, что используется при загрузке. У старых вложений lab4 staging и конечный original — один ключ: очистка снимает ссылку staging, но не удаляет оригинал.
Что показать преподавателю
Сначала make test, затем make test-lab5. Для воспроизводимого набора сбоев —
make verify-lab5 PYTHON=.venv/bin/python: команды и результаты сохраняются
в evidence/. Проверки отказов показывают реальные exit codes процессов,
неподтверждённую доставку, сохранение ID и неизменность конечных объектов.
Порядок устного объяснения:
- Чем 202 отличается от прежнего 201 и где исходник в этот момент.
- Как dispatcher найдёт задачу после crash между COMMIT и публикацией.
- Почему повтор нормален и почему число объектов не растёт.
- Что случится после S3 PUT до COMMIT результата и после COMMIT до ACK.
- Как lease, DB lock и лимит попыток помогают восстановлению.
- Как посмотреть failed и безопасно повторить его с audit.
В Redis успешный ответ XADD при выбранной конфигурации подтверждает принятие брокером; XACK означает завершение обработки consumer. В RabbitMQ аналогичные границы называются publisher confirm и consumer acknowledgement — это разные подтверждения.
Где читать код
- src/service/attachment.py — приём и атомарная запись queued + job/outbox.
- src/pipeline/dispatcher.py — публикация, lease recovery, staging cleanup.
- src/pipeline/worker.py — получение, retry, фиксация результата и ACK.
- src/pipeline/images.py — crop, thumbnail, WebP и лимиты дочернего процесса.
- src/pipeline/admin.py — реестр failed и явный replay.
- migrations/versions/009_pipeline.py — изменение схемы и переход с lab4.
- tests/lab5.py — HTTP и реальные fault-injection сценарии.
- tests/lab5_migration.py — сохранность старого вложения при миграции.