Files
mtusi2026lab5/REPORT.md
T
Vladislav Kunetskiy 01b885e846 lab5: очереди и асинхронная обработка изображений
Durable staging handoff, transactional outbox, at-least-once worker with lease fencing, idempotent versioned pipeline, three variants, operator tooling, contract tests and evidence. Includes the review fixes: reprocess source selection and failure settlement, replay guards, stale-job retirement, PNG structural/raster validation, migration rollback safety and audit events.
2026-10-31 14:34:24 +03:00

21 KiB
Raw Blame History

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

  • Автор, группа: Кунецкий Владислав, БВТ2303
  • Целевая оценка; выбранный трек 5: 5, трек 2 (доказанная идемпотентность pipeline)
  • Commit/PR: ветка lab5; история коммитов содержит перенос lab1–lab4 и базу контракта 1.5.0
  • Использованные источники, библиотеки и помощь ИИ: Go 1.27, PostgreSQL 18, RabbitMQ 4.3.7, SeaweedFS 3.80, HAProxy 3.2, AWS SDK for Go v2, ogen 1.24, sqlc, goose, mockery, github.com/gen2brain/webp (libwebp→WASM, CGo-free), golang.org/x/image, github.com/rabbitmq/amqp091-go. Внешние источники: контракт 1.5.0, contracts/attachment-states.md, contracts/jobs.schema.json, RabbitMQ quorum queue/delayed retry docs, PostgreSQL FOR UPDATE SKIP LOCKED, AWS presigned URL docs. ИИ-ассистент использовался для генерации кода и текста; все сценарии воспроизведены локально, результаты — в evidence/lab5/.

Запуск из чистого clone

Prerequisites: Docker Engine/Desktop с Compose v2, Python 3.10+ для публичных и студенческих тестов, Go 1.27 — только для unit/integration тестов и make generate. Образ собирает приложение сам.

git clone <repo> mtusi2026lab5 && cd mtusi2026lab5
git switch lab5
cp -n .env.example .env
make check
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# дождаться /health/ready (LB, localhost:8080), затем:
make test
make test-attachments
make test-presign
make test-queue
make test-faults
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh

Остановка без потери данных: docker compose --env-file .env down (named volumes сохраняются). Намеренное удаление учебных данных: docker compose --env-file .env down -v.

Стенд требует ~3–4 ГБ RAM Docker VM для worker (1G) + broker (384M) + существующих сервисов; в текущем окружении 2 ГБ, поэтому worker работает с WORKER_CONCURRENCY=1 и WORKER_MEM_LIMIT=1G как верхний предел, а не резервированием. Для серии с 40 Мп изображением нужен запас VM и замер RSS.

make check проверяет контракт, Python-синтаксис и S3 identities. make validate требует requirements-dev.txt:

python3 -m venv .venv && .venv/bin/pip install -r requirements-dev.txt
.venv/bin/python scripts/validate_openapi.py

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

flowchart LR
  C[client] -->|POST bytes| API[api x N]
  API -->|validate + spool| API
  API -->|Put staging| S3[(SeaweedFS S3)]
  API -->|TX: attachment queued + job + outbox| PG[(PostgreSQL)]
  RELAY[relay] -->|claim outbox + publisher confirm| MQ[(RabbitMQ quorum + DLQ)]
  MQ -->|at-least-once delivery| W[worker]
  W -->|read source, verify sha| S3
  W -->|Put original + variants| S3
  W -->|TX: variants + ready/retry/failed| PG
  W -->|ack after commit| MQ
  API -->|GET status/variants| PG
  API -->|GET content| S3
  RELAY -->|lease reaper| PG
  • API принимает байты, валидирует PNG/JPEG по содержимому (bytes, пиксели, MIME, filename), пишет оригинал в приватный S3 staging, затем одной транзакцией создаёт attachments(status=queued), attachment_jobs и outbox_messages. Только после этого возвращается 202 со снимком queued. API не публикует в broker и не делает resize.
  • Relay — отдельный процесс: читает outbox через FOR UPDATE SKIP LOCKED, публикует persistent сообщение с publisher confirm, помечает published_at только после ack. Там же lease reaper: просроченные processing возвращаются в queued с новым attempt, а исчерпавшие бюджет — в failed. Дополнительно reaper переиздаёт queued jobs без unpublished outbox-строки (потерянная доставка, dead-letter или data loss broker-а); worker CAS делает дубль безопасным.
  • Worker — отдельный процесс/контейнер. Claim через CAS, heartbeat, обработка, запись S3, затем одна транзакция результата; ack только после commit. Падение до ack приводит к redelivery; повтор видит готовый эффект и делает no-op ack.
  • PostgreSQL — истина о состоянии/намерении. S3 — байты. RabbitMQ — durable transport at-least-once, не источник истины. Границы: 202 = staging + TX intent; publisher confirm ≠ consumer ack.
  • Staging: staging/uploads/<chat>/<attachment>; presign проверенный объект копируется в staging/verified/...; финальный оригинал — attachments/<chat>/<attachment>/original; варианты — attachments/<chat>/<attachment>/variants/v<pipeline>/<name>.<ext>.
  • Эффект идемпотентен по (attachment_id, pipeline_version, variant): PK в attachment_variants, deterministic S3 keys, CAS по lease/attempt. ready терминален; старая версия не перезаписывает новую.
  • attachments.pipeline_version — опубликованная версия. jobctl reprocess создаёт job новой версии, но переключает pipeline_version и variants только в транзакции успешного завершения; до этого API продолжает отдавать старую готовую версию.
  • Presign — факультативное расширение вне OAS: presign создаёт internal pending-строку; complete проверяет байты, копирует их в server-owned verified staging и возвращает 202 queued.
  • Sweeper status-aware: staging queued/processing не удаляется; ready staging удаляется после безопасной фиксации; failed — после retention; orphan staging — после orphan grace. Referenced set включает финальные объекты, variants и активный staging; keyset-пагинация, fail-closed.
  • Admission control ограничивает число незавершённых rows (включая pending presign) на пользователя/стенд и объём staged bytes (429 rate_limited). Проверка повторяется внутри транзакции под PostgreSQL advisory lock, поэтому параллельные запросы не обходят cap; presign использует тот же механизм. Число одновременных upload-spool на процесс ограничено ADMISSION_MAX_CONCURRENT_UPLOADS, что ограничивает и временный диск API.

Соответствие .env.example реальной конфигурации

BROKER_URL, WORKER_CONCURRENCY, WORKER_PREFETCH, PROCESSING_*, OUTBOX_*, STAGING_*, ADMISSION_* читаются viper-ом (section.key → SECTION_KEY). S3_*, MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS, POSTGRES_*, REDIS_* сохранены с lab4. Compose подменяет localhost на имена сервисов для контейнеров; значения .env остаются локальными для запуска с хоста.

Доказательства критериев

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke, upload 201→202, thumbnail make test PASS lab5: 202→queued→ready, 256×160 JPEG, sha/size evidence/lab5/smoke.txt
202 после durable staging, worker отдельно make test-queue (lab5_async.py) worker stopped: 202 queued, content 409, ссылка на сообщение; после старта ready evidence/lab5/async.txt
Broker restart с volume lab5_async.py upload при остановленном broker → 202; после старта broker+relay ready evidence/lab5/async.txt
Полный restart стека lab5_async.py ready-вложение и original сохранились evidence/lab5/async.txt
Варианты: thumbnail/crop/optimized make test-queue/lab5_variants.py thumbnail 256×160 JPEG, crop 128×128 JPEG, optimized WebP 320×200; metadata == bytes; EXIF отсутствует evidence/lab5/variants.txt
Состояния queued/processing/ready/failed lab5_async.py, lab5_faults.py queued/ready и failed/error_code наблюдаются через API evidence/lab5/async.txt, faults.txt
415 на невалидное изображение make test-attachments пустое тело, IDAT-CRC, MIME spoof, не-zlib IDAT, пустой растр, недопустимый scanline-фильтр, несовместимые color type/bit depth, дубликаты IHDR, мусор после zlib, битый tRNS, PLTE сверх bit depth, tRNS сверх PLTE — 415 до 202 evidence/lab5/attachments-negative.txt
Original неизменен smoke + variants скачанные байты и sha совпадают с загруженными evidence/lab5/smoke.txt, variants.txt
Retry/backoff/classification make test-faults permanent → failed сразу; transient → 5 attempts, 4 retry events, retry_exhausted; DLQ evidence/lab5/faults.txt
DLQ/registry + replay lab5_faults.py failed виден в jobctl failed; replay → ready; replay ready refused evidence/lab5/faults.txt
Crash после записи объекта до ack lab5_faults.py redelivery, attempts=2, тот же набор из трёх variants evidence/lab5/faults.txt
Crash после claim до side effect lab5_faults.py lease/redelivery, attempts=2, ready evidence/lab5/faults.txt
Crash после commit до ack lab5_faults.py ready сохранился, повтор — no-op, attempt не вырос evidence/lab5/faults.txt
Outbox gap COMMIT→publish lab5_faults.py unpublished row → relay crash → recovery → published/ready evidence/lab5/faults.txt
Lease зависшего processing lab5_faults.py pause worker → lease expiry → requeue → fence stale → ready evidence/lab5/faults.txt
Persistence lab2+ make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS с broker/worker/relay в hook evidence/lab5/persistence.txt
Failover lab3+ make test-failover ACTION_SCRIPT=scripts/stop-one.sh 99 успешных записей, 0 ошибок, recovery 0.22 s evidence/lab5/failover.txt
Idempotency lab3+ make test-idempotency 1 accepted, 11 conflicts, stable replay evidence/lab5/idempotency.txt
LB исключает not-ready реплику make test-lb-readiness candidate 200→503, LB DOWN в пределах 30 s, 40 запросов без candidate evidence/lab5/lb-readiness-detail.txt
Трек 2: duplicate/stale/version python3 scripts/lab5_track2.py --reps 3 6/6 PASS: duplicate before effect, v1→v2, stale v1 no-op evidence/lab5/track2/

Параметры кодирования вариантов

pipeline_version thumbnail/crop JPEG optimized WebP WebP method EXIF/alpha
1 quality 85 quality 80 2 EXIF orientation применяется; metadata удаляется повторным encode; alpha компонуется на белый для JPEG
2 quality 70 quality 65 4 то же

Параметры закомпилированы в internal/imageproc.Pipeline и неизменны для версии; retry не может получить другие байты. Optimized не увеличивает изображение, fit ≤1280×1280.

Эксперименты и отказы

Воздействие Что ожидали Что наблюдали
Worker остановлен до upload 202 queued, content 409, работа не теряется 202, статус queued >2 s, после старта ready
Broker остановлен до upload 202, outbox intent сохраняется 202; после старта broker+relay ready
Relay убит после COMMIT до publish outbox остаётся, повтор публикует unpublished→published, ready, дублей эффекта нет
Worker убит после первого variant redelivery дописывает тот же набор attempts=2, три variants, original не изменён
Worker убит после commit до ack ready, повтор — no-op ready, attempt=1
Worker paused (lease) reaper вернёт работу, stale worker не запишет requeue, новый attempt, ready
Permanent error failed сразу, error_code, DLQ failed/injected_failure, attempts=1
Transient errors 5 attempts, backoff+jitter, failed attempts=5, retry_exhausted, DLQ
Failed replay failed→queued→ready без дубля ready, один thumbnail
v1 ready → reprocess v2 → old v1 delivery v2 не перезаписывается pv=2, variants v2, stale v1 ack
Reprocess queued при остановленном worker v2 берёт проверенный staging, а не несуществующий original pv=2 ready, v1 superseded, событие superseded записано
Reprocess v2 падает до публикации вложение терминально failed, не вечный queued failed/error_code, active jobs 0
Replay упавшей v2 до публикации API не показывает stale failed, работа возвращается job queued, attachment queued, затем ready:v2
Replay старой failed-v1 при наличии v2 команда отклонена, источник v2 не потерян v1 failed, v2 queued → ready:v2
Version-stale queued job после публикации v2 задание терминально superseded, не переиздаётся claim → superseded, reconcile не создаёт работу
Reprocess на неподдерживаемую версию команда отклонена, v1-задание не тронуто jobctl exit != 0, v1 queued → ready

Измерения: recovery времени и counts — из evidence/lab5/faults.txt, track2/runs.csv. Стенд: 2 vCPU, 2 ГБ Docker VM; синтетические пользователи/чат; fixture 320×200 PNG. Выводы — для локального Compose, не production SLA.

Ограничения

  • Доставка at-least-once, не exactly-once: crash между publish и confirm/ack даёт дубликат; эффект идемпотентен, но глобального exactly-once нет.
  • Single-node RabbitMQ: durability при рестарте с volume, но не HA/replication.
  • 40 Мп и 16-bit PNG не прогонялись в этой серии; worker имеет pixel cap, таймаут, watchdog и memory limit, но пиковый RSS на 40 Мп нужно измерять отдельно.
  • Track 2 — correctness harness (duplicate/stale/version + fault suite), не нагрузочный эксперимент; interleavings sampled, не исчерпаны.
  • Presign — optional extension; его ответ 202 и проверенный staging описаны в отчёте, но публичный контракт его не требует.
  • Rate limiting — admission cap с транзакционным reservation, не промышленный token bucket.
  • Presign подписывает URL статическим локальным app-identity; S3 API опубликован только на loopback для учебного стенда. В production нужен отдельный least-privilege signer и запрет локального доступа к bucket.
  • API readiness проверяет PostgreSQL, не S3/broker: при отказе S3 upload отвечает 503, но маршрутизация LB и чтение метаданных продолжают работать.
  • Reconciliation потерянной доставки запускается через OUTBOX_RECONCILE_AFTER (5m), поэтому dead-letter не теряет intent, но восстановление не мгновенное.
  • Failpoints включаются только FAULTS_ENABLED=1 при APP_ENV=dev; в обычном стенде инертны.
  • x-delivery-limit — immutable queue argument. На чистом стенде создаётся 100; при обновлении существующего volume очередь нужно пересоздать (или применить policy) до старта worker/relay.
  • Старые lab4 ready-вложения не переобрабатываются миграцией; для них нужен ручной jobctl reprocess (backfill в эту серию не входил).

Трек 2: гипотеза, методика, результаты

Гипотеза. При at-least-once доставке, effect key (attachment_id, pipeline_version, variant), deterministic S3 keys, serving-версии, меняющейся только после commit всех v2 variants, и ack stale-доставок pipeline не теряет принятую работу и не перезаписывает новый результат старым.

Методика. scripts/lab5_track2.py --reps 3: для каждой репетиции создаются новые пользователи/чат; (1) worker остановлен, upload, две duplicate-публикации одного job, затем worker стартует; (2) v1 ready → jobctl reprocess -pipeline 2 → v2 ready → публикуется старое v1-сообщение. Проверяются: уникальность variant rows, отсутствие регрессии ready, монотонность pipeline_version, неизменность original, no-op stale job. Fault suite дополнительно проверяет crash окна и lease.

Результаты. 6/6 сценариев PASS (evidence/lab5/track2/runs.csv), все fault-сценарии PASS. Исходные данные — evidence/lab5/track2/run.txt, summary.md, runs.csv.

Почему не exactly-once. Publisher confirm подтверждает приём брокером, consumer ack — устойчивый эффект; crash между ними создаёт повторную доставку. Идемпотентный effect key и CAS делают повтор безопасным, но не устраняют дубликаты доставки.

Ответы на вопросы защиты

  • Publisher confirm vs consumer ack: confirm — RabbitMQ durable accepted; ack — worker записал эффект. 202 не ждёт ни того, ни другого.
  • Что сохранено к 202: полный проверенный original в private S3 staging, attachment metadata queued, job intent и outbox row в одной TX. Thumbnail/final original/broker publish могут ещё не существовать.
  • Почему redelivery нормальна: at-least-once; effect key, deterministic keys, CAS lease/attempt, ready-no-op. Старый attempt/версия только ack-ается.
  • Stuck vs slow: heartbeat продлевает lease; живой медленный worker не забирается. Мёртвый перестаёт продлевать; reaper возвращает работу, старый CAS-fenced.
  • Replay: только failed, явный CLI, audit events, budget attempt-ов; ready replay запрещён.