16 KiB
Отчёт — лабораторная 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:
- блокирует attachment;
- переводит старые
queued/processingjobs вsupersededиpublished=true; - создаёт новую job версии
N; - обновляет
attachments.pipeline_versionиstatus=queued; - пишет
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.
Зафиксированные инварианты:
readyактивной версии ⇒ ровно три variant rows активной версии и нетqueued/processingjobs.- Не более одной активной job на attachment.
(attachment_id, pipeline_version, name)уникален; повтор не создаёт дубль.- Versioned object keys не позволяют старой версии перезаписать новую.
pipeline_versionповышается только аудированной транзакцией; стараяqueued/processingjob становитсяsuperseded.- Подтверждённые задачи не теряются после duplicate/reorder/stale/crash.
- Нет 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 дополнительно ограничивает worker1024m, 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 пропускной способности.