Files
mtusi2026lab5/REPORT.md
T
Mikhail Verkovykh fec2882c9a feat(lab5): track 1 queue experiment and evidence
- 3 profiles (serial 1/1, balanced 4/4, eager 8/32) x 2 image sizes
- measure throughput, DB-derived queue lag and p95 time-to-ready, worker RSS
- separate MAX_PENDING_JOBS=3 backpressure and worker recovery run
- self-contained HTML/SVG dashboard plus JSON/Markdown evidence
- document methodology, results and limitations in REPORT/README/CHANGELOG
2026-11-15 00:44:45 +03:00

263 lines
21 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
- Автор, группа: TODO
- Целевая оценка: **5**, трек 1 («Очередь под перегрузкой»)
- Commit/PR: 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
Требования: 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`.
## Архитектура и решения
```
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 (уровень 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` | 3 профиля × 2 размера; eager/small 13.86 jobs/s против serial 6.88; huge_few ~0.45 jobs/s у всех, RSS 205→1122 MiB; cap=3 дал 503 + Retry-After 5 и восстановление за 7.596 s | `evidence/track1.json`, `evidence/track1.html` |
## Эксперименты и отказы
| Воздействие | Что ожидали | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| 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 -->
### Гипотеза
Маленькие изображения, которые не требуют масштабирования, дешевле на задание:
выше throughput и ниже RSS. Большие изображения (2400×1800) требуют декодирования
и downscale до 1280×960, поэтому очередь растёт, p95 time-to-ready увеличивается,
а память сильнее зависит от concurrency. Дополнительно проверялся компромисс
«latency против ресурсов»: больше concurrency/prefetch должно снижать queue lag,
но повышать RSS.
### Методика
- Профили: `serial` 1/1, `balanced` 4/4, `eager` 8/32
(concurrency/prefetch).
- Сценарии: `small_many` — 30 PNG 192×128 (941 B, варианты не масштабируются);
`huge_few` — 12 PNG 2400×1800 (53 135 B, 4.32 MP, optimized уменьшается до
1280×960).
- Для каждой из 6 ячеек worker пересоздавался с профилем, поэтому RSS не
переносился из предыдущего прогона. Изображения загружались параллельно
(до 8 HTTP-клиентов). Все задания дожидались терминального состояния.
- Метрики берутся из PostgreSQL по `attachment_jobs`: queue lag =
`processing_started_at - created_at`, time-to-ready =
`finished_at - created_at`, processing = `finished_at - processing_started_at`.
Throughput = число ready / (последний `finished_at` − первый `created_at`).
- RSS — `VmRSS` процесса worker из `/proc/1/status`, сэмпл примерно каждые
100 мс; baseline снимался до загрузки.
- Worker ограничен **1 CPU**. На время эксперимента memory limit поднят до
**2 GiB** (в `.env` по умолчанию 1 GiB), иначе `eager/huge_few` упирался бы в
OOM, а не в измеряемый компромисс. Это зафиксировано в JSON.
- Backpressure: API пересоздан с `MAX_PENDING_JOBS=3`, worker остановлен,
upload-ы идут последовательно до первого `503`; затем worker запускается и
проверяется восстановление принятых заданий и новый probe upload.
Команда:
```sh
make track1 BASE_URL=http://localhost:8080
# или
python3 scripts/track1_experiment.py --base-url http://localhost:8080
```
Сырые данные: `evidence/track1.json`; графики: `evidence/track1.html`;
краткая таблица: `evidence/track1.md`.
### Результаты
| Профиль | Сценарий | Jobs/s | Queue lag p95, ms | Ready p95, ms | Processing p95, ms | RSS peak, MiB | Max parallel |
| --- | --- | ---: | ---: | ---: | ---: | ---: | ---: |
| serial | small_many | 6.875 | 3 194 | 3 284 | 113 | 28.2 | 1 |
| serial | huge_few | 0.443 | 23 333 | 25 521 | 2 308 | 204.7 | 1 |
| balanced | small_many | 11.590 | 1 624 | 1 736 | 209 | 30.6 | 4 |
| balanced | huge_few | 0.454 | 17 716 | 25 785 | 25 374 | 728.7 | 4 |
| eager | small_many | 13.858 | 898 | 1 158 | 284 | 32.7 | 8 |
| eager | huge_few | 0.459 | 17 538 | 25 699 | 24 979 | 1 122.1 | 8 |
Backpressure: cap `3`; первые 3 upload-а получили `202`, четвёртый — `503` с
`Retry-After: 5` и `error_code=unavailable`. После старта worker три принятых
задания стали `ready` за **7.596 s** (включая запуск контейнера и healthcheck),
после чего probe upload получил `202` и дошёл до `ready`.
### Выводы
1. **Размер изображения важнее числа заданий.** При `balanced` маленькие файлы
дают 11.59 jobs/s, большие — 0.454 jobs/s (в 25.5× меньше); p95 time-to-ready
растёт с 1 736 до 25 785 ms (в 14.9×). Processing p50 для huge — 8 460 ms
против 211 ms для small: доминирует декодирование/масштабирование, а не
ожидание в очереди.
2. **Eager хорошо работает на маленьких заданиях.** 13.86 jobs/s против 6.88 у
serial (2.0×), queue lag p95 падает с 3 194 до 898 ms, RSS растёт всего с
28.2 до 32.7 MiB. Это ожидаемый выигрыш от перекрытия лёгких задач.
3. **На huge_few concurrency не даёт throughput.** Все три профиля дают
~0.44–0.46 jobs/s: worker упирается в 1 CPU, а декодирование и WebP-кодирование
уже насыщают его. Queue lag p95 снижается (23.3 → 17.5 s), но p95
time-to-ready остаётся ~25.5 s: последние задания всё равно ждут своей доли
CPU. При этом RSS растёт с 205 MiB (serial) до 729 MiB (balanced) и
1 122 MiB (eager). **Больше concurrency здесь — не бесплатное ускорение, а
рост памяти при том же throughput.**
4. **Backpressure ограничивает принятую работу.** При cap=3 API перестал
принимать новые файлы до чтения тела и вернул retryable `503`; уже
подтверждённые задания не потерялись и завершились после возврата worker.
Это и есть требуемое «bounded acceptance + recovery».
5. **Практический выбор.** Для лёгких изображений разумен `balanced`/`eager`;
для тяжёлых при одном CPU лучше `balanced` (или `serial`, если важна память):
throughput тот же, а RSS в 1.5–5.5× ниже, чем у eager. `prefetch` больше
`concurrency` лишь держит сообщения у worker-а и не увеличивает параллельную
обработку.
### Ограничения эксперимента
- Один worker, один RabbitMQ, один PostgreSQL; это сравнение настроек, не HA и
не горизонтальное масштабирование.
- Worker ограничен 1 CPU и 2 GiB; на другом железе абсолютные числа и точка
насыщения будут другими. Относительный вывод «CPU-bound huge не ускоряется
concurrency» получен именно для этого лимита.
- PNG-фикстуры синтетические и хорошо сжимаются; доминирует стоимость
декодирования/масштабирования, а не сеть. Размеры в байтах и SHA-256 есть в
JSON.
- Один прогон на ячейку, без длительного прогрева и повторений; p95 по 12
заданиям чувствителен к выбросу. Это учебная оценка, не SLA.
- `MAX_PENDING_JOBS` проверяется приблизительно и не одной транзакцией с
вставкой; при нескольких API-репликах возможен небольшой перебор.
- Время восстановления backpressure включает `docker compose start` и
healthcheck, поэтому это верхняя оценка, а не время чистой обработки.
<!-- TRACK1:END -->
## Ограничения и следующие шаги
- Стенд учебный: один 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, если потребуется доказывать более сильную идемпотентность.