# 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 — сохранность старого вложения при миграции.