Files
mtusi2026lab5/REPORT.md
T

22 KiB
Raw Blame History

Отчёт — лабораторная 5

  • Автор, группа: Илья Тюнин, БВТ2303
  • Целевая оценка: 5, трек 2 «Доказанная идемпотентность pipeline»
  • Commit/PR: ветка lab5, коммиты lab5: ...; PR — после публикации
  • Источники: RabbitMQ reliability, RabbitMQ 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-прогонов. Образы приложения собираются из этого репозитория.

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 и укороченных таймаутов:

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 не попадают.

Архитектура и решения

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).