forked from mtusi2026/mtusi2026lab5
126 lines
10 KiB
Markdown
126 lines
10 KiB
Markdown
# 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 — сохранность старого вложения при миграции.
|