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

10 KiB
Raw Permalink Blame History

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

  1. Клиент передал все байты, прошли базовые проверки.
  2. В MinIO надёжно сохранён полный исходник в staging/.
  3. В одной транзакции PostgreSQL сохранены Attachment и AttachmentJob.
  4. Эта 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 и неизменность конечных объектов.

Порядок устного объяснения:

  1. Чем 202 отличается от прежнего 201 и где исходник в этот момент.
  2. Как dispatcher найдёт задачу после crash между COMMIT и публикацией.
  3. Почему повтор нормален и почему число объектов не растёт.
  4. Что случится после S3 PUT до COMMIT результата и после COMMIT до ACK.
  5. Как lease, DB lock и лимит попыток помогают восстановлению.
  6. Как посмотреть 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 — сохранность старого вложения при миграции.