Files
mtusi2026lab5/README.md
T
Mikhail Verkovykh 9e43faa536 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
2026-11-15 00:30:36 +03:00

165 lines
10 KiB
Markdown
Raw 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.
# Лабораторная 5. Очереди и асинхронная обработка изображений
Реализация лабораторной 5 на Go: API принимает файл, сохраняет оригинал в
durable staging, фиксирует задание в PostgreSQL и отвечает **202**. Отдельный
worker обрабатывает задание через RabbitMQ и делает варианты изображения.
Целевая оценка — **5, трек 1** (очередь под перегрузкой).
[Карта курса](COURSE.md) · [Процесс fork/PR](CONTRIBUTING.md) · [OpenAPI](contracts/openapi.json) · [Семантика API](contracts/README.md) · [Проверки](tests/README.md) · [Отчёт](REPORT.md) · [Примеры JSON](contracts/examples.json) · [Changelog](CHANGELOG.md)
## Стек и состав стенда
| Компонент | Версия | Роль |
| --- | --- | --- |
| Go + Fiber v3 | Go 1.27.1 | API, worker, reconciler |
| PostgreSQL | 16.10 | источник истины: attachments, jobs/outbox, idempotency |
| RabbitMQ | 4.2 | durable quorum queue `attachment.process.v1` |
| RustFS (S3) | 1.0.4 | staging и конечные объекты, private bucket |
| Redis | 7.4.7 | сессии |
| HAProxy | 3.2.6 | балансировка двух API-реплик |
Контейнеры: `postgres`, `redis`, `rustfs`, `s3-init`, `migrate`, два `api`,
`worker`, `reconciler`, `haproxy`. Секреты живут только в локальном `.env`.
## Запуск из чистого clone
Нужны Docker Engine с Compose v2 и Python 3.9+ для проверок.
```sh
cp .env.example .env
# Заполните только секреты; S3_ACCESS_KEY_ID и S3_APP_USER должны совпадать.
python3 - <<'PY'
from pathlib import Path
import secrets
p = Path(".env")
text = p.read_text()
for key in ("POSTGRES_PASSWORD", "S3_ROOT_ACCESS_KEY", "S3_ROOT_SECRET_KEY",
"S3_SECRET_ACCESS_KEY", "RABBITMQ_PASSWORD"):
text = "\n".join(
f"{key}={secrets.token_urlsafe(24)}" if line.startswith(key + "=") else line
for line in text.splitlines()
) + "\n"
p.write_text(text)
PY
docker compose --env-file .env up -d --build
# Дождитесь healthy у api/worker и 200 от readiness.
curl -fsS http://localhost:8080/health/ready
make test BASE_URL=http://localhost:8080
```
`migrate` применяет миграции 0001–0005, `s3-init` идемпотентно создаёт private
bucket и scoped-пользователя. Повторный `up -d` не удаляет volumes. Полная
остановка без потери данных — `docker compose down`; намеренное удаление
учебных данных — `docker compose down -v` (разрушительно).
Если Docker не может скачать базовые образы из-за DNS, соберите приложение на
хосте и запустите без сборки:
```sh
DOCKER_BUILDKIT=1 docker build --network=host -t mtusi2026lab-api:local .
docker compose --env-file .env up -d --no-build
```
## Как устроен путь файла
1. **API / upload.** Проверяются членство в чате, имя и `Content-Type`, затем
тело потоково копируется в temp-файл (буфер 32 KiB) с SHA-256. Байтовый
лимит 10 MiB и пиксельный лимит 40 MP проверяются до выделения памяти под
декодирование. Валидный оригинал кладётся в `staging/{chat}/{attachment}`.
2. **Одна транзакция.** В PostgreSQL вставляются `attachments` (`queued`) и
`attachment_jobs` (`published_at IS NULL`). Только после COMMIT клиент
получает `202`; в этот момент durable уже и байты, и намерение.
3. **Outbox → RabbitMQ.** Каждая API-реплика (и worker) раз в 250 мс публикует
непубликованные строки в quorum queue с persistent delivery и ждёт publisher
confirm. Затем `published_at` выставляется compare-and-set. Падение между
COMMIT и publish восстанавливается следующим проходом.
4. **Worker.** Сообщение содержит только `job_id`, `attachment_id`, версию и
попытку — без байтов, ключей и credentials. Worker берёт DB-lease, заново
читает доверенные метаданные, сверяет размер и SHA-256 staging-объекта.
5. **Эффект.** Оригинал копируется без изменений в `attachments/...`; рядом
пишутся детерминированные варианты `thumbnail`, `crop`, `optimized`.
`CompleteJob` атомарно ставит `ready` только для текущей попытки/версии.
Лишь после этого staging удаляется, а сообщение подтверждается (ack).
6. **Клиент** опрашивает `GET /api/v1/attachments/{id}` до `ready`; content
отдаётся только для `ready`, иначе `409`.
### Варианты
| Имя | Формат | Правило |
| --- | --- | --- |
| `thumbnail` | JPEG q=85 | fit в 256×256, белый фон, без upscale |
| `crop` | JPEG q=85 | центральный квадрат 128×128 |
| `optimized` | WebP q=82 | fit в 1280×1280, без upscale |
EXIF orientation применяется до преобразований. Оригинал сохраняется
byte-for-byte и сохраняет исходный SHA-256. Метаданные вариантов не
копируются. Все операции детерминированы: повторная доставка перезаписывает
те же ключи теми же байтами.
### Надёжность и повторы
- Очередь — RabbitMQ quorum queue, сообщения persistent, publisher confirms.
- Ack только после durable effect (или осознанного no-op). `ErrRequeue`
используется, если не удалось записать состояние в PostgreSQL.
- Ошибки делятся на постоянные и временные. Временные повторяются с
экспоненциальным backoff ±50% jitter, до `JOB_MAX_ATTEMPTS`.
- Постоянная ошибка даёт `failed` с безопасным `error_code`; реестр failed
виден через API, явный replay — `worker -replay <attachment_uuid>`.
- Просроченный lease (`processing` без живого worker) возвращается в очередь
sweeper-ом. Повтор не создаёт второй набор вариантов.
- `MAX_PENDING_JOBS` — приблизительный admission cap: при переполнении upload
получает `503` и `Retry-After: 5`, не доходя до чтения тела.
- Reconciler удаляет только брошенные staging/pending-объекты после grace
period; готовые вложения не трогает.
## Конфигурация
Все переменные и значения по умолчанию перечислены в `.env.example`. Главные:
| Переменная | Смысл |
| --- | --- |
| `MAX_UPLOAD_BYTES` | байтовый лимит, не больше 10 MiB |
| `MAX_IMAGE_PIXELS` | пиксельный лимит, не больше 40 MP |
| `IMAGE_DECODE_MEMORY_MB` | общий budget декодирования на процесс |
| `WORKER_CONCURRENCY` / `WORKER_PREFETCH` | параллелизм handler-ов / unacked сообщений |
| `MAX_PENDING_JOBS` | admission cap очереди (0 — выключен) |
| `JOB_MAX_ATTEMPTS`, `JOB_TIMEOUT_SECONDS`, `JOB_LEASE_SECONDS` | retry/lease policy |
| `JOB_RETRY_BASE_SECONDS`, `JOB_RETRY_MAX_SECONDS` | backoff |
| `WORKER_FAULT_MODE`, `WORKER_CRASH_AFTER_EFFECT`, `WORKER_CRASH_AFTER_CLAIM` | детерминированные хуки для доказательств |
## Проверки и доказательства
```sh
make check
make test BASE_URL=http://localhost:8080 # публичный smoke
python3 tests/custom/attachments.py --base-url ... # 413/415/404/400, без 5xx
python3 tests/custom/attachment_flow.py --base-url ... # сквозной upload/download
python3 tests/custom/concurrent_uploads.py --base-url ... # конкурентные upload
python3 scripts/lab5_resilience.py --base-url ... # 6 сценариев уровня 4
python3 scripts/track1_experiment.py # трек 1 уровня 5
```
`scripts/lab5_resilience.py` останавливает worker и RabbitMQ, внедряет crash
до/после эффекта, проверяет retry, replay и lease recovery. Результаты —
`evidence/lab5-grade4.{json,md}`. Persistence/failover проверяются публичными
`make test-persistence` / `make test-failover` с `scripts/restart.sh` и
`scripts/stop-one.sh`; см. `evidence/lab5-persistence*` и `evidence/lab5-failover.txt`.
Трек 1 запускает матрицу профилей `serial/balanced/eager` на маленьких и
больших изображениях, измеряет throughput, queue lag, p95 time-to-ready и RSS,
затем отдельно показывает backpressure и восстановление. Результаты и графики
описаны в [REPORT.md](REPORT.md).
## Ограничения
Стенд учебный и однокомпонентный по каждому сервису: RabbitMQ и PostgreSQL
запущены в одном экземпляре, поэтому отказ их контейнера проверяется
перезапуском с volume, а не HA-кластером. `MAX_PENDING_JOBS` считается по
каждой API-реплике отдельно, это приблизительный, а не глобальный лимит.
Измерения RSS на Docker Desktop/в CI могут отличаться от bare-metal. Секреты,
tokens и содержимое пользовательских файлов в evidence не сохраняются.