29 KiB
Отчёт — лабораторная 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:
- все байты приняты в
staging/<id>/original; размер и SHA-256 сверены,ImageInspectorи полный decode проверили контейнер и пиксели; attachments— строкаqueuedсsize_bytes,sha256,width,height;attachment_jobs— логическая работа(attachment_id, pipeline_version),attempt=1,max_attempts;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) параллельно: измеренный
пик — 992.2 MiB / 1.25 GiB (в предыдущих прогонах 934–966 MiB), 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 Мп параллельно, пик 934–992 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 |
| Регрессия ревью: потерянное сообщение | purge очереди после publish | reconciler вернул job, ready за 5.1 s, событие reconciled |
reconciler.txt |
| Регрессия ревью: рестарт broker | restart broker при живом worker | consumer вернулся, следующий upload ready | broker-resubscribe.txt |
| Разделение RabbitMQ identities | broker-init + rabbitmqctl list_permissions |
API не читает attachments.process; worker — отдельный пользователь |
broker-identities.txt |
Эксперименты и отказы
Гипотеза трека 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; пик 934–992 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) не
защищены.
Исправления по независимому ревью
После первого зелёного прогона ревью выявило латентные отказы; внесены правки:
- Потеря queued job после DLQ/исчезнувшего сообщения:
LeaseReaperтеперь периодически вызываетreconcileQueuedJobs; job без unpublished outbox получает новую outbox-строку.claimпри ошибке БД повторяется с задержкой, nack отложен, поэтому delivery limit не сжигается в tight loop. - Потеря consumer после рестарта broker:
BrokerClientотслеживаетsubscribing, повторяетbasic.consumeпри закрытии канала,basic.cancelи ошибке подписки; частично установленное соединение закрывается. - Publish без подтверждения/маршрута: добавлены timeout подтверждения,
mandatory: trueи обработкаbasic.return; outbox не помечает строку published при возврате. - Clock skew «not_due»: due-check выполняется в SQL (
next_attempt_at <= now()). - Порядок блокировок: claim/reap/replay/cleaner блокируют job, затем attachment; это исключает 40P01 между claim и commit.
- Staging cleaner vs replay: удаление объекта выполняется под row-lock
вместе с
clearStaging; replay ждёт и видитqueued. - Relay в worker: retry и lease-expiry публикуются даже при недоступном API; при ошибке relay использует backoff.
- Варианты и lease: ключ варианта содержит attempt
(
.../<variant>-a<attempt>.<ext>); потерявший lease worker не перезапишет объект, на который смотрит БД. - Долгий рендер: общий дедлайн распределяется по операциям sharp, abort проверяется между ними.
- Терминальное событие reaper: при
retry_exhaustedпишетсяfailed. - Direct upload cap: проверка лимита и insert сериализованы advisory-lock.
- Retention: опубликованный outbox и старые события чистятся по TTL,
добавлен индекс
job_outbox(job_id). - Legacy lab4 rows: миграция 008 ставит им v1 job в outbox, чтобы появились
варианты, а не пустой
variants: []. - Least privilege: API теряет
DeleteObjectна варианты (толькоattachments/*/original), S3 policies ограничены префиксами; RabbitMQ разделён наmessenger(публикация, без чтения очереди) иmessenger-worker(consumption),broker-initприводит существующий volume к этой схеме.
Осталось осознанным упрощением: финальный оригинал permanently failed job сохраняется для операторского replay, staging удаляется по retention.
Повторное ревью и вторые правки
Второй независимый проход не нашёл P0/P1, но выявил последствия первых правок; они устранены:
withTransactionснимаетerror-события checked-out pg-клиента иrelease(error), поэтомуidle_in_transaction_session_timeoutне роняет процесс; relay дополнительно ограничен бюджетом< idle_timeout/2.- Reconciler срабатывает только при пустой очереди и отсчитывает grace от
job_outbox.published_at, поэтому нормальный backlog не размножается. - Миграция 009 добавляет partial index по
queuedjobs, индексы поjob_events(created_at)иjob_outbox(published_at); pruning стал пакетным. - Reconciliation пишется отдельным событием
reconciled, а неretry_scheduled, чтобы не искажать счётчик retry. - После успеха/исчерпания попыток worker удаляет варианты старых attempt
(
-aN), для чего worker получилDeleteObjectтолько наattachments/*/v*/*. replayпередаёт ожидаемыйstaging_keyи под блокировкой отказываетsource_changed, если cleaner успел изменить источник.- Publisher снимает метрику ровно один раз (
settled), confirm-channelclose/errorобрабатываются, а сбой consumer-подписки больше не рвёт рабочее publish-соединение. - RabbitMQ разделён на
messenger(API: публикация и topology, без чтения очереди) иmessenger-worker(consumption); одноразовыйbroker-initсоздаёт второго пользователя и сужает права первого.
Ограничения и следующие шаги
- Реализованы уровни 3–4 и трек 2; трек 1 (сравнение concurrency/prefetch) не заявлен.
- Финальный original permanently failed job не удаляется автоматически: он нужен для безопасного replay, пока staging ещё не истёк; ручная очистка описана в отчёте.
- Брокер и S3 — single-node; production-варианты требуют кворумов и ретраев между зонами.
job_outboxпубликуется одним relay-процессом на реплику; при росте нагрузки нужен отдельный relay или партиционирование.- Ошибки классифицируются по сообщению sharp/
SERVER_FAULT; для новых форматов список стоит расширять по мере появления. - Следующий шаг: метрики очереди lag и p95 ready, отдельный DLQ-replay UI, сравнение concurrency/prefetch (трек 1).