Files
mtusi2026lab5/REPORT.md
T

313 lines
22 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
- Автор, группа: Илья Тюнин, БВТ2303
- Целевая оценка: 5, трек 2 «Доказанная идемпотентность pipeline»
- Commit/PR: ветка `lab5`, коммиты `lab5: ...`; PR — после публикации
- Источники: [RabbitMQ reliability](https://www.rabbitmq.com/docs/reliability), [RabbitMQ confirms](https://www.rabbitmq.com/docs/confirms), `contracts/jobs.schema.json`, `contracts/attachment-states.md`, amqplib 2.2.1, sharp 0.35.5. ИИ использован для черновика плана, ревью кода и текста отчёта; решения и проверки выполнены и воспроизведены локально.
## Запуск из чистого clone
Требования: Docker 29.x с Compose v2, Python 3.9+, Node 25.7.0 для локальных
юнит/e2e-прогонов. Образы приложения собираются из этого репозитория.
```sh
make init-env # .env (если нет) + secrets/*; значения не печатаются
make check # offline-структура и OpenAPI
make stand-up # build + PostgreSQL, Redis, MinIO, RabbitMQ, API x2, worker, HAProxy
make wait-ready # /health/ready
make test # публичный smoke: 202 -> ready -> thumbnail 256x160
make test-e2e # e2e приложения против стенда
make test-dependencies # отказы Redis/PostgreSQL/S3, пауза S3, saturation
make test-persistence ACTION_SCRIPT=scripts/restart.sh
scripts/start-replica.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
make lab5-demo # worker остановлен -> upload 202 -> рестарт broker/API -> ready
```
Проверка трека 2 требует включённого fault injection и укороченных таймаутов:
```sh
FAULT_INJECTION_ENABLED=1 JOB_TIMEOUT_SECONDS=10 JOB_LEASE_SECONDS=8 \
JOB_RETRY_BASE_MS=500 JOB_RETRY_MAX_MS=4000 make stand-up
make lab5-faults # level4 -> evidence/lab5/faults-level4.json
make lab5-track2 # track2 x3 -> evidence/lab5/track2.json
make stand-up # вернуть штатные значения
```
Остановка: `make stand-down`. Намеренное удаление учебных данных (необратимо):
`docker compose --env-file .env down -v` — удаляет PostgreSQL, Redis, MinIO и
RabbitMQ volumes. Секреты лежат в `secrets/` и в Git не попадают.
## Архитектура и решения
```mermaid
flowchart LR
C[client] --> H[HAProxy]
H --> A1[API 1]
H --> A2[API 2]
A1 --> PG[(PostgreSQL)]
A2 --> PG
A1 --> S3S[(S3 staging/*)]
A1 --> O[(job_outbox)]
O --> R[Outbox relay]
R --> MQ[(RabbitMQ quorum queue)]
MQ --> W[worker]
W --> S3F[(S3 attachments/*)]
W --> PG
A1 --> RDS[(Redis: sessions, cache, faults)]
```
Источник истины — PostgreSQL. Брокер только доставляет сообщение; S3 хранит
байты. API и worker — разные процессы, worker не импортирует HTTP-модули.
### Состояния
| `attachments.status` | Значения |
| --- | --- |
| публичные | `queued`, `processing`, `ready`, `failed` |
| внутренние | `pending` (идёт приём), `deleting`, `rejected` (lab4) |
| `attachment_jobs.status` | Значения |
| --- | --- |
| | `queued`, `processing`, `succeeded`, `failed`, `superseded` |
Правила переходов выполняются в транзакции, меняющей job:
- claim: `queued -> processing` только при `attachments.status='queued'`;
- success: `ready`, если `coalesce(ready_pipeline_version,0) <= pipeline_version`,
иначе job становится `superseded`, а строка вложения не меняется;
- retry: `processing -> queued` только при `attachments.status='processing'`;
- final failure: `failed` + `error_code`, только если вложение не `ready`;
- replay: `failed -> queued`;
- `ready` никогда не откатывается; старая job не перезаписывает новый результат.
### Что уже сохранено в момент 202
До ответа 202 выполняются и фиксируются одним COMMIT:
1. все байты приняты в `staging/<id>/original`; размер и SHA-256 сверены,
`ImageInspector` и полный decode проверили контейнер и пиксели;
2. `attachments` — строка `queued` с `size_bytes`, `sha256`, `width`, `height`;
3. `attachment_jobs` — логическая работа `(attachment_id, pipeline_version)`,
`attempt=1`, `max_attempts`;
4. `job_outbox` — намерение опубликовать сообщение.
Только после COMMIT вызывается fault point `api.after_commit_before_publish` и
relay. Брокер не входит в `/health/ready`: outbox позволяет принимать загрузки
при недоступном RabbitMQ, а relay опубликует задание после восстановления.
### Окна отказа
| Окно из contract | Механизм | Сценарий | Доказательство |
| --- | --- | --- | --- |
| после staging до записи задания | строка `pending` + `expires_at`; sweeper удаляет staging и строку | lab4 sweep + `make test-dependencies` | `make-test-dependencies.txt` |
| после COMMIT до publish | transactional outbox, relay повторяет непомеченные строки | `crash_after_commit_before_publish` | `faults-level4.json` |
| после publish до confirm | ConfirmChannel; без confirm транзакция relay откатывается | `relay_crash_after_publish` | `track2.json` |
| после записи S3 до COMMIT результата | lease истекает, reaper возвращает job в `queued`; повторный рендер детерминирован | `crash_after_side_effect` | `track2.json` |
| после COMMIT результата до ack | redelivery видит `succeeded` и отвечает `duplicate_skipped` | `crash_after_commit_before_ack` | `track2.json` |
### Publisher confirm и consumer ack
- **Publisher confirm** — брокер принял persistent-сообщение. Outbox помечает
строку опубликованной только после confirm.
- **Consumer ack** — worker устойчиво зафиксировал эффект в PostgreSQL и S3.
Ack после commit; падение между commit и ack даёт redelivery и no-op.
Это at-least-once доставка. Ключ эффекта — `(attachment_id, pipeline_version,
variant)` (PK `attachment_variants`); логическая работа уникальна по
`(attachment_id, pipeline_version)`. Повторная доставка не создаёт второй набор
вариантов. `attempt` увеличивается только управляемым retry/replay/истечением
lease, но не redelivery брокера.
### Зависший worker и долгая работа
Claim ставит `lease_owner`, `lease_token`, `lease_until`. Heartbeat продлевает
lease каждые `JOB_LEASE_SECONDS/3`; 0 обновлённых строк означает потерю lease и
аборт job. `JOB_TIMEOUT_SECONDS` — жёсткий дедлайн: `AbortController` плюс
`sharp(...).timeout({seconds})` дают transient `processing_timeout`. Reaper
возвращает job с истёкшим lease в очередь, поэтому убитый worker не оставляет
вечный `processing`.
### DLQ, failed registry, replay
- **DLQ** (`attachments.process.dlq`): невалидный JSON/схема и сообщение,
не совпадающее с job (`mismatch`). Это не очередь повторных попыток.
- **Failed registry**: `cli failed` — jobs в `failed` с `last_error_code`.
- **Replay** (`cli replay`) разрешён только для failed job, при отсутствии
активной job, и отказывает `already_ready`, `no_failed_job`, `job_active`,
`source_expired`. Новая попытка защищена тем же ключом эффекта; успешный
результат не исполняется повторно.
### Staging retention
Worker удаляет `staging/<id>/original` после успешного commit. Остатки убирает
`StagingCleaner`: для `ready` — через минуту, для `failed` — через
`STAGING_RETENTION_SECONDS` (24 ч). Pending/rejected загрузки удаляет lab4
sweeper по `expires_at + grace`. Текущую работу cleaner не трогает.
### Качество вариантов и метаданные
| Вариант | v1 | v2 |
| --- | --- | --- |
| thumbnail | JPEG q80, fit 256×256, без апскейла, alpha на белом | JPEG q90 progressive mozjpeg |
| crop | JPEG q80, 128×128 cover centre (апскейл разрешён) | JPEG q90 progressive mozjpeg |
| optimized | WebP q75 effort 4, fit 1280×1280 | WebP q82 effort 5 smartSubsample |
EXIF orientation применяется `.rotate()`; размеры берутся из
`metadata().autoOrient`. sharp по умолчанию удаляет EXIF/ICC (нет
`withMetadata`). `fitInside` использует целочисленную арифметику: 320×200 →
256×160, 1000×335 → 256×85, 10000×1 → 256×1.
### Память worker
База ≈250 MiB + `WORKER_CONCURRENCY × (10 MiB исходник + ≈340 MiB худший декод
40 Мп)` ≈ 950 MiB при concurrency 2. Лимит `WORKER_MEMORY=1280m`.
`big_image` загружает два `worst_decode_png` (8000×5000) параллельно: измеренный
пик — **966.3 MiB / 1.25 GiB**, `OOMKilled=false`, оба вложения дошли до ready.
Запас ~300 MiB; при росте concurrency лимит нужно поднимать вместе с бюджетом.
### Конфигурация
| Переменная | Фактическое значение / роль |
| --- | --- |
| `BROKER_URL_FILE` | `/run/secrets/broker_url`, amqp URL с паролем из secret |
| `BROKER_DELIVERY_LIMIT` | 10, `x-delivery-limit` quorum-очереди |
| `WORKER_CONCURRENCY` | 2, prefetch и число параллельных job |
| `JOB_MAX_ATTEMPTS` | 5, ограниченные retry |
| `JOB_TIMEOUT_SECONDS` | 60, жёсткий дедлайн рендера |
| `JOB_LEASE_SECONDS` | 30, lease + heartbeat/3 |
| `JOB_RETRY_BASE_MS` / `JOB_RETRY_MAX_MS` | 1000 / 30000, equal jitter |
| `PIPELINE_VERSION` | 1, версия для новых upload |
| `OUTBOX_POLL_INTERVAL_MS` | 500, период relay |
| `LEASE_REAPER_INTERVAL_MS` | 2000 |
| `STAGING_CLEANUP_INTERVAL_MS` | 60000, 0 отключает |
| `STAGING_RETENTION_SECONDS` | 86400 |
| `WORKER_HEALTH_PORT` | 8081 |
| `FAULT_INJECTION_ENABLED` | 0 в штатном стенде, 1 для suite |
| `WORKER_REPLICAS` / `WORKER_CPUS` / `WORKER_MEMORY` | 1 / 1.5 / 1280m |
| `BROKER_CPUS` / `BROKER_MEMORY` | 0.5 / 512m |
Остальные переменные lab4 (`DATABASE_URL`, `REDIS_URL`, S3, лимиты загрузки,
таймауты) сохранены; `S3_ACCESS_KEY_ID_FILE`/`S3_SECRET_ACCESS_KEY_FILE`
подменяются в worker на отдельную identity.
### Роли инфраструктуры
| Роль | Service | Образ | Готовность | Volume | Credentials |
| --- | --- | --- | --- | --- | --- |
| API | `api` | сборка `mtusi-messenger:lab5` | `/health/ready` (PG/Redis/S3) | — | `s3_api_*`, `broker_url` |
| Worker | `worker` | та же сборка, `dist/worker.main.js` | `127.0.0.1:8081/health` | — | `s3_worker_*`, `broker_url` |
| Broker | `broker` | `rabbitmq:4.1.8-alpine@sha256:153322e3974e6365c50e523e5eadd5a7fae231f0e8c58f67c03bb3e02056e34e` | `rabbitmq-diagnostics check_port_connectivity` | `broker-data` | `rabbitmq.conf` |
| PostgreSQL | `postgres` | `postgres:16.4-alpine` | `pg_isready` | `postgres-data` | `.env` / `DATABASE_URL` |
| Redis | `redis` | `redis:7.4.2-alpine` | `redis-cli ping` | `redis-data` | только compose-сеть |
| S3 | `s3` | `minio/minio:RELEASE.2025-09-07T16-13-09Z@sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e` | `mc ready local` | `s3-data` | root secrets |
| S3 bootstrap | `s3-init` | `minio/mc:...@sha256:a7fe349ef4bd8521fb8497f55c6042871b2ae640607cf99d9bede5e9bdf11727` | exit 0 | — | root + API/worker |
| LB | `haproxy` | `haproxy:3.2-alpine` | depends on api healthy | — | — |
### Изменения относительно lab4
- upload 201 → 202 `queued`; metadata отдаёт `queued/processing/ready/failed`,
`error_code` и `variants`;
- байты пишутся в `staging/*`, worker переносит оригинал в `attachments/*`;
- добавлены `attachment_jobs`, `attachment_variants`, `job_outbox`, `job_events`;
- добавлены broker, worker, отдельные S3-identity и политики;
- `openContent` отдаёт `original/thumbnail/crop/optimized` и 409 до ready;
- сообщения можно привязывать к `queued/processing` вложениям, failed даёт 409;
- сохранены lab4-механизмы: idempotency, cache, drain, sweeper, direct upload,
failover/persistence hooks.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл |
| --- | --- | --- | --- |
| Сборка и lint | `npm run build && npm run lint` | без ошибок; `dist/worker.main.js` и `dist/jobs/jobs.cli.js` | `build-lint.txt` |
| Публичный smoke | `make test` | `PASS: lab5 public API scenario`; 202 → ready → thumbnail 256×160 JPEG, sha совпал | `evidence/lab5/make-test.txt` |
| «3»: API 202 только после устойчивого приёма | `make test`, `make lab5-demo` | staging + attachment + job + outbox в одном COMMIT; worker остановлен, upload принят | `make-test.txt`, `worker-down-demo.txt` |
| «3»: отдельные broker и worker | `make lab5-demo`, `docker compose ps` | broker/worker healthy; worker не в API-процессе | `compose-ps.txt`, `worker-down-demo.txt` |
| «3»: состояния и thumbnail | `make test`, `make test-e2e` | metadata `queued/processing/ready`; thumbnail 256×160; original неизменен | `make-test.txt`, `make-test-e2e.txt` |
| «3»: ограниченный retry и failed | `retry_and_replay` | 4 `retry_scheduled`, затем `failed`/`retry_exhausted`; replay → ready | `faults-level4.json` |
| «3»: принятое задание переживает рестарт broker | `make lab5-demo` | quorum-очередь сохранила сообщение после restart broker+API | `worker-down-demo.txt`, `queues.txt` |
| «4»: crop/optimized, качество, EXIF | `make test`, unit `pipelines.spec.ts` | 128×128 JPEG, WebP 320×200, EXIF 6 → 170×256, прозрачность на белом | `unit-tests.txt`, `make-test.txt` |
| «4»: outbox, crash COMMIT→publish | `crash_after_commit_before_publish` | attachment готов без ручного создания job; один `created` | `faults-level4.json` |
| «4»: backoff/jitter, permanent/transient, DLQ/failed/replay | `retry_and_replay`, `poison` | transient exhausted, DLQ +2, replay с audit | `faults-level4.json` |
| «4»: crash после S3 до ack | `crash_after_side_effect` | attempt 2, lease_expired, варианты байт-идентичны baseline | `faults-level4.json`, `track2.json` |
| «4»: timeout/lease, concurrency, очистка staging | `hung_worker`, `make lab5-demo`, CLI status | `processing_timeout` retry; `staging_present=false` после ready | `faults-level4.json`, `queues.txt` |
| «4»: память worker на 40 Мп | `big_image` | 2 × 40 Мп параллельно, пик 577–966 MiB, OOMKilled=false | `big-image-memory.txt`, `faults-level4.json` |
| «5» трек 2: версионирование, дубль, reorder, crash, stale | `make lab5-track2` | все инварианты I1–I6 истинны на 3 повторах | `track2.json` |
| «5» трек 2: отсутствие потери и перезаписи | `stale_version` | ready_pipeline_version=2, v1 `superseded`, v2 etag не изменился | `track2.json` |
| «5» трек 2: не exactly-once доставка | отчёт, `duplicate` | 5 duplicate publish дали 5 `duplicate_skipped`, S3 etag не изменился | `track2.json` |
## Эксперименты и отказы
### Гипотеза трека 2
At-least-once delivery + DB-fenced claim + versioned effect keys дают
**exactly-once effects** для `(attachment_id, pipeline_version, variant)` при
дубле, reorder, crash до/после side effect и устаревшей job после новой версии.
Доставка при этом остаётся at-least-once: дубли и повторные публикации
наблюдаются и поглощаются, а не исчезают.
### Методика
- Стенд: 8 vCPU (i7-11370H), 15 GiB RAM; worker 1 реплика, concurrency 2,
лимит 1280 MiB; broker 0.5 CPU / 512 MiB; JOB_TIMEOUT_SECONDS=10,
JOB_LEASE_SECONDS=8, retry 500–4000 ms; `track2` повторён 3 раза.
- Перед сценариями загружается reference и запоминаются SHA-256 вариантов v1.
- Каждый сценарий начинается и заканчивается очисткой `fault:*`; timeline
опрашивается каждые 200 мс.
- Инварианты:
- **I1** — ready (или ожидаемый failed) не позже 60 с;
- **I2** — ровно 3 варианта ready-версии и ровно одно `succeeded` на job;
- **I3** — ready не откатывается, `ready_pipeline_version` не убывает;
- **I4** — подтверждённая работа не потеряна (есть успешный эффект);
- **I5** — нет дублей `(pipeline_version, variant)`;
- **I6** — SHA-256 вариантов совпадает с baseline для той же версии.
### Результаты
Таблица заполняется из `evidence/lab5/track2.json` и
`evidence/lab5/faults-level4.json`; фактические значения и пик памяти worker
приведены в `evidence/lab5/summary.md`.
| Сценарий | Группа | Наблюдение (3 повтора для track2) |
| --- | --- | --- |
| `duplicate` | track2 | 5 повторных publish → 5 `duplicate_skipped` (`already_succeeded`); S3 etag/last_modified не изменились; attempt 1 |
| `reorder` | track2 | attempt 99 и дубль attempt 1 поглощены; ровно 2 skip, 1 `succeeded`; attempt 1 |
| `crash_before_side_effect` | track2 | worker убит до S3; попытка 2, `lease_expired`, процесс worker перезапущен |
| `crash_after_side_effect` | track2 | попытка 2, `lease_expired`, SHA-256 вариантов совпал с baseline (I6) |
| `crash_after_commit_before_ack` | track2 | попытка 1, один `succeeded`, redelivery → `duplicate_skipped` (`already_succeeded`) |
| `relay_crash_after_publish` | track2 | API убит между publish и mark; relay опубликовал снова, дубль поглощён; все 3 повтора |
| `stale_version` | track2 | `ready_pipeline_version=2`, v1 `superseded`, остались только варианты v2, v2 etag не изменились, served thumbnail SHA ≠ v1 |
| `crash_after_commit_before_publish` | level4 | API убит после COMMIT; outbox relay опубликовал после рестарта; ровно один `created`, ready |
| `retry_and_replay` | level4 | 4 `retry_scheduled`, затем `failed`/`retry_exhausted`; replay → attempt 6 → ready; `replayed` с operator |
| `hung_worker` | level4 | abort по `JOB_TIMEOUT_SECONDS`, `retry_scheduled` с `processing_timeout`, затем ready |
| `poison` | level4 | два невалидных сообщения ушли в DLQ, jobs не созданы |
| `big_image` | level4 | оба 40 Мп вложения ready, `OOMKilled=false`; пик 577–966 MiB при лимите 1280 MiB |
Итог: `level4` — **7/7**, `track2` — **21/21** (7 сценариев × 3), все
инварианты I1–I6 истинны; см. `evidence/lab5/faults-level4.json`,
`evidence/lab5/track2.json`.
### Ограничения эксперимента
Это не exactly-once **доставка**: redelivery и повторная публикация наблюдаются.
S3-запись может повториться (объект перезаписывается тем же детерминированным
байтом), PostgreSQL — одна нода, а fault points находятся внутри процесса.
Сценарии `relay_crash_after_publish` и `crash_after_commit_before_publish`
зависят от гонки relay и поэтому фиксируют наблюдение, если дубль не успел
возникнуть. Внешние эффекты за пределами `(attachment, version, variant)` не
защищены.
## Ограничения и следующие шаги
- Реализованы уровни 3–4 и трек 2; трек 1 (сравнение concurrency/prefetch) не
заявлен.
- Брокер и S3 — single-node; production-варианты требуют кворумов и ретраев
между зонами.
- `job_outbox` публикуется одним relay-процессом на реплику; при росте нагрузки
нужен отдельный relay или партиционирование.
- Ошибки классифицируются по сообщению sharp/`SERVER_FAULT`; для новых
форматов список стоит расширять по мере появления.
- Следующий шаг: метрики очереди lag и p95 ready, отдельный DLQ-replay UI,
сравнение concurrency/prefetch (трек 1).