feat(lab5): durable async attachment pipeline through grade 4

- RabbitMQ quorum queue, persistent messages and publisher confirms
- S3 staging plus PostgreSQL attachments/jobs outbox transaction
- worker variants (thumbnail, crop, optimized WebP), DB lease and lease sweeper
- jittered retry, permanent failures, explicit replay and admission cap
- deterministic crash hooks, resilience script and evidence for grade 4
- async-aware custom tests, oversized pixel case, docs and changelog
This commit is contained in:
Mikhail Verkovykh
2026-11-15 00:30:36 +03:00
parent 28d68dc30b
commit 9e43faa536
48 changed files with 4077 additions and 333 deletions
+142 -15
View File
@@ -1,37 +1,164 @@
# Отчёт — лабораторная 5
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Целевая оценка: **5**, трек 1 («Очередь под перегрузкой»)
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Использованные источники и библиотеки: RabbitMQ quorum queues и publisher
confirms; `amqp091-go`, `gen2brain/webp`, `golang.org/x/image/draw`,
`golang.org/x/sync/semaphore`; стандартные `image/png`, `image/jpeg`.
Генерация отчёта и графиков — Python standard library. ИИ-ассистент
использовался для реализации, ревью кода и подготовки текста; все
приведённые результаты получены запуском команд на этом стенде.
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Требования: Docker Engine + Compose v2, Python 3.9+. Точные версии образов
закреплены в `compose.yaml` (PostgreSQL 16.10, RabbitMQ 4.2, RustFS 1.0.4,
Redis 7.4.7, HAProxy 3.2.6); приложение собирается из `golang:1.27.1-alpine`.
```sh
cp .env.example .env
# Заполнить POSTGRES_PASSWORD, S3_ROOT_ACCESS_KEY, S3_ROOT_SECRET_KEY,
# S3_SECRET_ACCESS_KEY, RABBITMQ_PASSWORD. S3_ACCESS_KEY_ID и S3_APP_USER
# обязаны совпадать: RustFS использует имя пользователя как access key.
docker compose --env-file .env up -d --build
curl -fsS http://localhost:8080/health/ready
make test BASE_URL=http://localhost:8080
```
`migrate` применяет миграции 0001–0005; `s3-init` создаёт приватный bucket и
scoped-пользователя. Оператору не нужно вручную создавать очередь: worker и
publisher объявляют durable quorum queue `attachment.process.v1`.
Безопасная остановка: `docker compose down` (volumes сохраняются).
Намеренное удаление учебных данных: `docker compose down -v`. Секреты в git не
попадают; `.env` находится в `.gitignore`.
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab4, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
```
client ──HTTP──> API ──stream──> staging/{chat}/{attachment} (S3)
│
└─ ONE TX: attachments(queued) + attachment_jobs(outbox)
│
outbox loop │ publisher confirm
v
RabbitMQ quorum queue
│ at-least-once
v
worker
DB lease ─> read metadata ─> verify staging
│
├─> attachments/{chat}/{attachment} (original, byte-equal)
├─> .../thumbnail (JPEG 256 fit)
├─> .../crop (JPEG 128 square)
└─> .../optimized (WebP 1280 fit)
│
└─ CompleteJob (attempt/version CAS) ─> ready
│
ack + delete staging
```
**Источник истины — PostgreSQL.** Сообщение RabbitMQ — только идентификатор и
снимок намерения; worker перечитывает attachment из БД. Поэтому подмена
сообщения не даёт доступа к чужим байтам, а повторная доставка безопасна.
**Граница 202.** До ответа выполнены: авторизация, валидация заголовка и
лимитов, потоковая запись во временный файл, SHA-256, PUT в durable staging и
одна транзакция, создающая attachment + job. Ответ `202` означает «байты и
намерение сохранены», а не «resize выполнен».
**Outbox.** `attachment_jobs.published_at IS NULL` — committed intent без
publisher confirm. Outbox-цикл работает в каждой API-реплике и в worker; дубли
публикации схлопываются DB-lease. Это закрывает окно «COMMIT прошёл, publish
не прошёл».
**Идемпотентность эффекта.** `ClaimJob` выдаёт lease только одной попытке.
`CompleteJob` обновляет строку при совпадении `job_id + attempt + processing` и
проверяет `pipeline_version`; устаревшая попытка не может перезаписать новый
результат. Ключи вариантов детерминированы, повтор пишет те же байты.
**Retry.** Постоянные ошибки (`invalid_image`, `staging_corrupt`,
`staging_missing`) сразу дают `failed`. Временные (`storage_unavailable`,
`processing_timeout`, `processing_failed`) повторяются с экспоненциальным
backoff ±50% jitter до `JOB_MAX_ATTEMPTS`. После исчерпания — `failed` с
`retry_exhausted`. Явный replay: `docker compose exec worker /usr/local/bin/worker -replay <uuid>`.
**Память и лимиты.** Upload не использует `io.ReadAll`: тело копируется
буфером 32 KiB. API и worker декодируют изображение только после проверки
`width*height`, под общим semaphore-budget `IMAGE_DECODE_MEMORY_MB`. Байтовый
лимит 10 MiB и пиксельный 40 MP — жёсткие сверху, конфигурация может только
ужесточить их.
**Reconciler.** Удаляет только брошенные `pending`-строки и объекты без
метаданных после grace period; `ready` не трогает. Это не часть happy path, а
страховка от падений между PUT и COMMIT.
## Доказательства критериев
Все команды выполнялись на локальном Compose-стенде; из sandbox-контейнера
использовался адрес Docker host `http://172.18.0.1:8080`, для обычного хоста —
`http://localhost:8080`. Токены и секреты не сохранены.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
| Публичный smoke (уровень 3) | `make test` | `PASS: lab5 public API scenario`; upload 202 → ready, оригинал и JPEG thumbnail проверены | `evidence/lab5-smoke.txt` |
| Upload 202 только после durable приёма | `scripts/lab5_resilience.py` сценарий `worker_stopped` | worker остановлен: `202 queued`, content `409`, после старта worker — `ready`; queue 2.316 s | `evidence/lab5-grade4.json` |
| Отдельные broker и worker | `docker compose ps` | контейнеры `rabbitmq`, `worker`, два `api`, `postgres`, `rustfs`, `reconciler` | `evidence/lab5-persistence-containers.txt` |
| Остановка API/broker не теряет принятое | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS; все контейнеры перезапущены с новыми `StartedAt`, volumes сохранены | `evidence/lab5-persistence.txt`, `evidence/lab5-persistence-containers.txt` |
| Broker outage / outbox | сценарий `broker_outage` | 202 при выключенном RabbitMQ, `published_at IS NULL`, readiness 200; после старта broker job опубликован и ready, attempt 1 | `evidence/lab5-grade4.json` |
| Retry с backoff и jitter | сценарий `transient_retry` | первая попытка failed, retry через 2.25 s, attempt 2 → ready | `evidence/lab5-grade4.md` |
| Permanent failure + replay | сценарий `permanent_failure_replay` | `invalid_image`, content/link 409, replay_count 1, после replay ready, 3 варианта | `evidence/lab5-grade4.json` |
| Crash после эффекта до ack | сценарий `crash_after_effect` | worker restart 0→1, повтор завершает ту же job, 3 варианта | `evidence/lab5-grade4.md` |
| Зависший processing / lease | сценарий `lease_recovery` | one-shot exit 10, статус processing, sweeper вернул job, attempt 2 → ready | `evidence/lab5-grade4.md` |
| Ограниченная конкуренция/prefetch | конфигурация worker | `WORKER_CONCURRENCY`, `WORKER_PREFETCH`, `ch.Qos(prefetch)`; матрица трека 1 | `REPORT.md`, `evidence/track1.json` |
| Очистка staging после фиксации | сценарии `worker_stopped`, `crash_after_effect` | `staging_cleared: true`; reconciler удаляет только брошенное | `evidence/lab5-grade4.json`, `evidence/reconcile.txt` |
| Негативные случаи и лимиты | `python3 tests/custom/attachments.py` | 413 по bytes и по 42 MP, 415 corrupt/spoof, 404/400, нет 5xx | `evidence/lab5-negative-cases.txt` |
| Failover API | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | 118 успешных записей, 1 переходная ошибка, восстановление 2.659 s; остановлена именно `api-2` | `evidence/lab5-failover.txt` |
| Трек 1, уровень 5 | `python3 scripts/track1_experiment.py` | см. раздел «Эксперимент трека 1» ниже | `evidence/track1.json`, `evidence/track1.html` |
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| Воздействие | Что ожидали | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
| Worker остановлен после upload | 202, content 409, job ждёт | 202 queued; после старта ready, attempt 1 | 2.316 s до ready, потерь нет |
| RabbitMQ остановлен между COMMIT и publish | 202 и восстановление outbox | 202, `published_at IS NULL`, readiness 200; после старта job ready | 9.005 s до ready, потерь нет |
| Worker `exit 9` после записи вариантов до ack | redelivery завершает ту же job | restart 0→1, 3 объекта, ready | без потери и без второго набора |
| Worker `exit 10` после claim | lease истекает, sweeper возвращает job | processing → recovered → attempt 2 → ready | 8 s (lease sweep), потерь нет |
| Временная ошибка storage | retry с jitter | attempt 1 failed, attempt 2 ready | ~2.25 s backoff |
| Постоянная ошибка `invalid_image` | failed + безопасный replay | content/link 409, replay_count 1, ready | ручной replay, без дубля |
| Остановка одной API-реплики | сессия и подтверждённые данные живы | 118 успешных записей, 1 ошибка, recovery 2.659 s | потерь нет |
| Перезапуск всех контейнеров с volumes | данные и сессия сохраняются | persistence PASS, новые `StartedAt` | потерь нет |
### Ограничения измерения отказов
`restart.sh` перезапускает контейнеры, а не эмулирует падение ядра или потеру
диска. RabbitMQ и PostgreSQL — одиночные экземпляры, поэтому это проверка
durability на volume, а не HA-кластера. Failover измеряет один API-инстанс за
HAProxy; отказ БД или брокера в этом сценарии не имитируется. Времена включают
опрос готовности и запуск контейнера, поэтому это верхняя оценка, не SLA.
## Эксперимент трека 1 (уровень 5)
<!-- TRACK1:START -->
Будет заполнено после запуска `scripts/track1_experiment.py`: гипотеза, профили,
размеры изображений, throughput, queue lag, p95 time-to-ready, RSS,
backpressure и восстановление. Сырые данные — `evidence/track1.json`, графики —
`evidence/track1.html`.
<!-- TRACK1:END -->
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
- Стенд учебный: один RabbitMQ, один PostgreSQL, один worker; горизонтальное
масштабирование worker проверяется конфигурацией, но не HA-кластером.
- `MAX_PENDING_JOBS` считается по репликам приблизительно; глобальный лимит
потребовал бы общего счётчика (например, Redis) и отдельной транзакционной
семантики.
- Replay намеренно ручной и явный: автоматический replay постоянных ошибок
маскировал бы дефекты входных данных.
- WebP-энкодер `gen2brain/webp` выбран без CGO; качество и скорость могут
отличаться от libwebp CLI, но результаты детерминированы на стенде.
- Измерения RSS зависят от cgroup/докер-обвязки; для production нужен
длительный профиль и p99, а не короткий учебный прогон.
- Следующий шаг: versioned pipeline и автоматический fault-injection для
трека 2, если потребуется доказывать более сильную идемпотентность.