# Отчёт — лабораторная 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//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//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).