Files
mtusi2026lab5/REPORT.md
T
2026-11-19 10:57:39 +03:00

16 KiB
Raw Blame History

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

  • Автор, группа: Антипин Егор Иванович
  • Целевая оценка: 5, трек 2 «Доказанная идемпотентность pipeline»
  • Commit/PR: TODO после публикации
  • Библиотеки: Spring AMQP, RabbitMQ Java client, Thumbnailator, webp-imageio, MinIO SDK, PostgreSQL/Flyway
  • Помощь ИИ: проектирование versioned pipeline, fencing и fault-injection, реализация, подготовка тестов и черновиков evidence; результат проверен сборкой, unit-, black-box- и аварийными тестами

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

Нужны Docker Desktop/Engine с Compose v2, Java 23 и Python 3.9+.

cp .env.example .env
# Заменить все replace-with-* уникальными локальными значениями.
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
python -X utf8 tests/smoke.py --base-url http://localhost:8080

Автоматические student_tests/lab5_*.py используют .env.example и рассчитаны на одноразовый учебный стенд; для них удобно поднимать Compose с тем же файлом:

docker compose --env-file .env.example up -d --build
python -X utf8 student_tests/lab5_pipeline_idempotency.py

docker compose --env-file .env down сохраняет volumes. Удаление учебных данных выполняется только явной командой оператора с --volumes.

Pipeline и гарантии

Upload разделён на durable-границы: API проверяет bytes/MIME/dimensions, пишет неизменённый original в приватный staging/<attachment_id>/original, затем одной транзакцией создаёт attachments(queued) и attachment_jobs(published=false). Запись job является transactional outbox. Фоновый publisher публикует persistent JSON в durable RabbitMQ queue, ждёт publisher confirm и только потом помечает job опубликованной. Поэтому COMMIT без publish восстанавливается автоматически, а HTTP 202 означает, что staging и намерение обработки уже устойчивы.

Отдельный worker захватывает job с lease, читает доверенный staging key из PostgreSQL и создаёт детерминированные S3 keys. В broker message есть только schema_version, job_id, attachment_id, pipeline_version, attempt, created_at; bytes, credentials, произвольные URL и клиентские пути отсутствуют. Эффект идемпотентен по (attachment_id, pipeline_version, variant). Все variant rows и ready фиксируются атомарно; ack выполняется после COMMIT. Redelivery уже ready job — no-op.

Обязательные варианты для активной версии:

Вариант Правило Формат/качество
original bytes и SHA-256 совпадают с upload исходный MIME
thumbnail fit в 256×256, без увеличения, EXIF orientation, alpha на белом JPEG, quality зависит от версии
crop центрированный квадрат 128×128 после EXIF orientation JPEG, quality зависит от версии
optimized fit до 1280×1280, без увеличения, alpha сохраняется WebP, quality зависит от версии

Новые файлы кодируются из пикселей без копирования EXIF/ICC/прочих исходных metadata.

Versioned pipeline v1/v2

Миграция V7__versioned_pipeline_and_fault_points.sql добавляет:

  • attachments.pipeline_version;
  • уникальность attachment_jobs(attachment_id, pipeline_version);
  • состояние superseded;
  • audit-таблицу attachment_pipeline_promotions;
  • маркеры fault-injection до и после side effect.

ImageVariantProcessor выбирает профиль по pipeline_version: v1 и v2 имеют разные quality для JPEG/WebP, поэтому результаты версий различаются побайтово. Ключи объектов версионированы: thumbnail-v1.jpg, thumbnail-v2.jpg, optimized-v1.webp и т.д.; общий original неизменяем. Старая версия физически не может перезаписать объект новой версии. Одна и та же pipeline_version обязана быть детерминированной: изменение quality/алгоритма оформляется новой версией, иначе ON CONFLICT DO NOTHING сохранит уже записанные variant rows.

Повышение версии — одна аудированная транзакция scripts/promote-pipeline.ps1/.sh:

  1. блокирует attachment;
  2. переводит старые queued/processing jobs в superseded и published=true;
  3. создаёт новую job версии N;
  4. обновляет attachments.pipeline_version и status=queued;
  5. пишет attachment_pipeline_promotions.

Fencing выполняется в каждом переходе состояния: claim, markReady, markFailed, retry, expired-lease recovery и replay проверяют одновременно job.pipeline_version, attachments.pipeline_version, lease token и terminal state. Поэтому старая job после promotion не может ни получить lease, ни записать variants, ни перевести attachment в ready.

Если v1 уже удалил staging после безопасного COMMIT, worker версии v2 читает неизменяемый attachments/<id>/original; содержимое и SHA-256 те же.

Fault injection и инварианты

Точка Поведение
FAULT_CRASH_AFTER_OUTBOX_COMMIT API падает после COMMIT attachment/outbox, до publish; republisher восстанавливает намерение
FAULT_CRASH_BEFORE_SIDE_EFFECT worker падает до S3 PUT; lease истекает, reaper возвращает job в outbox
FAULT_CRASH_AFTER_SIDE_EFFECT worker падает после детерминированных S3 PUT, до result COMMIT; повтор сходится к тем же объектам
FAULT_CRASH_AFTER_RESULT_COMMIT worker падает после atomic ready COMMIT, до consumer ack; redelivery — no-op

Все флаги по умолчанию выключены и предназначены только для изолированного стенда. Автоматический student_tests/lab5_pipeline_idempotency.py проверяет:

  • duplicate: две одинаковые v2-доставки дают один результат;
  • reorder: v2 доставляется раньше stale v1;
  • stale: v1 после v2 не меняет snapshot активного результата;
  • superseded: повышение ещё queued v1 job отменяет её без variant rows;
  • crash до S3 side effect: 0 объектов, 0 result rows, восстановление через повторную попытку;
  • crash после S3 side effect: 4 объекта до COMMIT, после повтора — те же 4 объекта и ровно 3 variant rows;
  • crash после result COMMIT: redelivery не дублирует variants;
  • все 5 подтверждённых вложений остаются ready.

Зафиксированные инварианты:

  1. ready активной версии ⇒ ровно три variant rows активной версии и нет queued/processing jobs.
  2. Не более одной активной job на attachment.
  3. (attachment_id, pipeline_version, name) уникален; повтор не создаёт дубль.
  4. Versioned object keys не позволяют старой версии перезаписать новую.
  5. pipeline_version повышается только аудированной транзакцией; старая queued/processing job становится superseded.
  6. Подтверждённые задачи не теряются после duplicate/reorder/stale/crash.
  7. Нет variant rows версии больше активной.

Почему это не exactly-once доставка

RabbitMQ обеспечивает at-least-once: сообщение может быть доставлено повторно после потери соединения или падения worker до ack; порядок сообщений не является бизнес-порядком. Publisher confirm подтверждает только приём брокером, а consumer ack идёт после PostgreSQL COMMIT. Между S3 PUT и COMMIT нет распределённой транзакции, поэтому crash в этом окне оставляет уже выполненные side effects и вызывает повторную обработку.

Идемпотентность достигнута на уровне эффекта, а не доставки: deterministic object keys, ON CONFLICT DO NOTHING, уникальные PK и conditional markReady приводят любые повторы к одному наблюдаемому состоянию активной версии. То же самое можно назвать effectively-once результатом при at-least-once доставке. Exactly-once доставка потребовала бы транзакционной связи RabbitMQ, PostgreSQL и S3 или эквивалентного распределённого протокола; в этой учебной архитектуре её нет, и тест сознательно демонстрирует лишние повторы S3 PUT, которые не меняют результат.

Ограничения worker и retry

  • Upload: MAX_UPLOAD_BYTES=10485760, MAX_IMAGE_PIXELS=40000000.
  • Worker повторно проверяет header/dimensions до полного decode и применяет тот же pixel cap.
  • Оценка памяти на job резервируется общим честным semaphore; бюджет WORKER_MEMORY_BUDGET_BYTES=536870912, ожидание WORKER_MEMORY_WAIT=2s. Compose дополнительно ограничивает worker 1024m, JVM использует до 70% container RAM.
  • Обработка ограничена JOB_TIMEOUT=60s; просроченный task теряет lease и не может зафиксировать результат.
  • WORKER_CONCURRENCY=2, WORKER_PREFETCH=1; lease 90s, reaper каждые 5s.
  • Не более JOB_MAX_ATTEMPTS=5. Временные ошибки получают exponential backoff с jitter 50–100% и cap 30s. Ошибки decode/format/size постоянные и сразу становятся безопасным failed/error_code; exhausted retry — retry_exhausted.
  • Permanent malformed broker delivery и исчерпанная работа dead-lettered в durable attachments.failed.v1. Реестр failed остаётся в PostgreSQL.

Операторский replay выполняется scripts/replay-failed.ps1 -JobId <uuid> или scripts/replay-failed.sh <uuid>. Одна транзакция блокирует одновременно failed job и attachment, пишет attachment_job_replays, сбрасывает outbox и состояние. Не-failed, уже recovered и ready jobs дают явный безопасный no-op; replay также требует совпадения pipeline_version.

После безопасного COMMIT результата worker best-effort удаляет staging. StagingCleaner удаляет только неактивные объекты старше STAGING_RETENTION_SECONDS=86400; queued/processing staging защищён. Отдельного GC для orphan-объектов старых версий после promotion «в полёте» нет: active результат они не перезаписывают, но место могут занимать.

Проверки

Критерий Команда Результат
Unit + integration gradlew test BUILD SUCCESSFUL, 30 tests
Contract/Compose python -X utf8 scripts/check_contract.py; docker compose --env-file .env.example config --quiet PASS, exit 0
Публичный smoke python -X utf8 tests/smoke.py --base-url http://localhost:8080 PASS
Трек 5.2 python -X utf8 student_tests/lab5_pipeline_idempotency.py PASS: version fencing, superseded, duplicate/reorder, pre/post-side-effect crashes
Worker stop/restart, redelivery python -X utf8 student_tests/lab5_worker_recovery.py PASS; original неизменен, 3 variants, duplicate не создаёт rows
COMMIT→publish и result COMMIT→ack python -X utf8 student_tests/lab5_fault_injection.py PASS; обе задачи дошли до ready
DLQ, replay, lease python -X utf8 student_tests/lab5_dlq_replay_lease.py PASS; DLQ +1, одна audit-запись, ready не replayed, expired lease восстановлен
Lab3: shared idempotency python -X utf8 student_tests/idempotency_concurrent.py PASS; 32 запроса, 2 реплики, одно сообщение
Lab3: readiness gate python -X utf8 student_tests/readiness_gate.py PASS; обе реплики 503 на сломанной схеме и восстановились
Lab3: failover каждой реплики python -X utf8 student_tests/failover_each.py ... PASS; 2 реплики, confirmed writes сохранены
Lab3: rolling update python -X utf8 student_tests/rolling_update.py ... PASS; 4 instance ID, 335 успешных записей, 3 переходных отказа
Lab4: negative python -X utf8 student_tests/lab4_negative.py PASS; ownership/MIME/corruption/limit/filename
Lab4: upload memory python -X utf8 student_tests/concurrent_upload_memory.py ... PASS; 12/12 uploads, 2 API реплики

Подробный журнал с SQL-инвариантами и JSON-агрегатами: evidence/lab5-level5-2026-11-19.md. Предыдущие уровни: evidence/lab5-level4-2026-11-19.md, evidence/lab4-2026-11-11.md.

Ограничения

  • Один Docker-host, по одному экземпляру PostgreSQL, RabbitMQ, Redis и MinIO; эксперимент не доказывает отказоустойчивость к потере host/диска.
  • Exactly-once доставки нет; доказан at-least-once + идемпотентный эффект.
  • Versioned orphan-объекты старых версий после promotion «в полёте» не перезаписывают active результат, но автоматического GC для них нет.
  • promote-pipeline — операторский скрипт с SQL-транзакцией, не публичный API.
  • Исторические 3 attachment от 2026-11-18 созданы до V7 и имеют один вариант; на чистом volume и для новых данных действует инвариант трёх вариантов.
  • Числа failover/rolling — проверка сохранности на одном Windows-хосте, не benchmark пропускной способности.