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

126 lines
10 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 — сохранность старого вложения при миграции.