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.
21 KiB
Отчёт — лабораторная 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, PostgreSQLFOR 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 переиздаётqueuedjobs без 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 (включая
pendingpresign) на пользователя/стенд и объём staged bytes (429rate_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 запрещён.