Files
mtusi2026lab5/REPORT.md
2026-11-10 16:21:46 +03:00

21 KiB
Raw Permalink Blame History

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

  • Автор, группа: Чурилин Данила, БВТ2301
  • Текущий завершённый уровень: оценка «5»
  • Выбранный трек 5: трек 2 — доказанная идемпотентность versioned pipeline
  • Ветка: solution/bvt2301-churilin
  • Commit/PR: пока не созданы по просьбе автора; весь уровень 5 и финальный аудит подготовлены к одному коммиту
  • Использованные источники, библиотеки и помощь ИИ: Go standard library, amqp091-go, disintegration/imaging, pure-Go go-webp v0.4.0, PostgreSQL/pgx, MinIO SDK и RabbitMQ; OpenAI Codex использован для проектирования, реализации, fault injection, тестирования и отчёта

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

Нужны Docker Engine с Compose v2, GNU Make, Python 3.9+ и OpenSSL. Go локально не нужен: builder закреплён как golang:1.27.1-alpine.

cp .env.example .env
make init-secrets

docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
docker compose --env-file .env up -d --wait

make check
make test BASE_URL=http://127.0.0.1:8080
make test-async-resilience BASE_URL=http://127.0.0.1:8080
make test-level4-resilience BASE_URL=http://127.0.0.1:8080
make test-level5-idempotency BASE_URL=http://127.0.0.1:8080

make init-secrets создаёт локальные файлы с mode 600 в игнорируемом secrets/ и не перезаписывает существующие значения. Миграции выполняет одноразовый migrate; minio-bootstrap идемпотентно создаёт приватный bucket, ограниченную policy и отдельного S3-пользователя.

Операторские команды failed registry, replay и versioned pipeline:

make jobs-failed
make replay-job JOB_ID=<uuid-failed-job>
make upgrade-pipeline ATTACHMENT_ID=<uuid> PIPELINE_VERSION=2
make inject-job JOB_ID=<uuid>

Replay разрешён только для failed, требует ещё сохранённый staging и записывает audit event. Попытка replay для queued, processing или succeeded завершается ошибкой без изменения job.

Безопасная остановка с сохранением данных:

docker compose --env-file .env down

Намеренное удаление всех учебных данных:

docker compose --env-file .env down --volumes

Архитектура и транзакционные границы

client -> HAProxy -> API x2
                    |-- MinIO staging/{attachment_id}/original
                    '-- PostgreSQL attachment + attachment_job/outbox (COMMIT)
                                           |
                                       dispatcher
                         lease reaper <----+----> publisher confirm
                                           |
                                durable RabbitMQ queue
                                           |
                           manual ack -> worker (prefetch=2)
                    |-- MinIO original + v{1,2}/{thumbnail,crop,optimized}
                    '-- PostgreSQL variants + ready/succeeded (COMMIT)
                                           |
                               delete/clear staging

Источники истины:

  • PostgreSQL: состояния, metadata, job/outbox, available_at, lease, failed registry и audit events;
  • MinIO: durable staging и конечные объекты;
  • RabbitMQ: persistent at-least-once transport;
  • Redis: восстанавливаемый cache, не источник истины.

Граница ответа 202

  1. API ограниченно читает максимум 10 MiB, проверяет MIME, полный decode и максимум 40 млн пикселей.
  2. Проверенный оригинал устойчиво записывается в приватный MinIO staging.
  3. attachments(status=queued) и attachment_jobs(status=queued, attempt=1) фиксируются одной транзакцией PostgreSQL.
  4. Только после успешного commit возвращается 202 Accepted. Resize в API не выполняется.

Job-row одновременно является outbox-записью. Dispatcher выбирает только queued AND published_at IS NULL AND available_at <= now(), публикует persistent-message в durable queue, ждёт publisher confirm и затем ставит publish-marker. Если процесс падает после DB commit до publish, строка остаётся видимой. Если он падает после confirm до marker, будет безопасный дубль.

Broker message содержит только schema/job/attachment/pipeline/attempt и время. Bytes, credentials, произвольный URL и клиентский filename в очередь не попадают.

Media pipeline

Worker повторно проверяет размер, SHA-256 и pixel limit, применяет EXIF orientation и создаёт:

Variant Формат и параметры Геометрия
thumbnail JPEG quality 85 (v1) / 90 (v2), alpha на белом fit 256×256, floor, минимум 1 px, без upscale
crop JPEG quality 85 (v1) / 90 (v2), alpha на белом центрированный square 128×128, upscale разрешён
optimized lossy WebP quality 80 (v1) / 85 (v2) fit 1280×1280, floor, без upscale, alpha сохраняется

Все варианты строятся из декодированных ориентированных пикселей. EXIF/ICC/XMP не передаются кодировщикам, поэтому metadata удаляется. WebP вызывается через cancellable EncodeContext. Новые upload используют v1; операторский upgrade повторно ставит готовый или остановленный после side effect original в v2 через отдельный durable staging.

Ограничения ресурсов worker:

  • повторная проверка 10 MiB и 40 млн пикселей до полного worker-decode;
  • JOB_TIMEOUT_SECONDS=60;
  • GOMEMLIMIT=448MiB и hard Compose limit 512 MiB;
  • concurrency/prefetch равны 2;
  • lease 75 секунд, то есть длиннее timeout;
  • S3/DB операции имеют отдельные bounded timeouts.

Идемпотентность, retry и lease

Ключ эффекта — (attachment_id, pipeline_version, variant); это PK таблицы вариантов. Object keys детерминированы и содержат версию. Все три variant metadata и переход ready/succeeded фиксируются одной DB-транзакцией. Повтор не создаёт новые строки и не откатывает ready.

Upgrade v1→v2 сначала создаёт новый durable staging из неизменного final original, затем одной PostgreSQL-транзакцией меняет активную attachments.pipeline_version, переводит прежнюю queued/processing job в superseded и создаёт v2 job/outbox. Completion, retry, permanent failure, replay и lease recovery сравнивают версию job с активной версией attachment. Устаревший результат может оставить объект только в своём /v1/ prefix, но не публикует metadata и не очищает v2 staging.

Transient error:

  • job processing -> queued;
  • attempt увеличивается;
  • published_at и lease сбрасываются;
  • available_at получает exponential backoff;
  • base 250 ms, cap 4 s, deterministic per-job jitter в диапазоне 0.5–1.5;
  • после пятой попытки: job failed/processing_failed, attachment failed/retry_exhausted.

Permanent error (invalid_image, staging_expired, unsupported_pipeline) сразу переводит активную job в failed без расходования остальных попыток. Устаревшая версия получает superseded без изменения активного attachment. Все переходы регистрируются в attachment_job_events.

При claim worker ставит lease_until и leased_by. Dispatcher reaper возвращает просроченную processing-job в queued с новой попыткой и backoff. Старое broker-сообщение после смены attempt становится no-op. Сообщение для уже удалённой job также ack-ается как stale no-op, а не образует poison requeue loop.

Staging cleanup

После commit результата worker удаляет staging и очищает attachments.staging_key. Фоновый cleaner запускается при старте и каждые 30 секунд:

  • ready staging удаляется немедленно как избыточный;
  • failed staging и DB-orphan удаляются только старше retention 24 часа;
  • queued/processing staging не удаляется независимо от возраста;
  • replay после retention безопасно отклоняется.

Fault injection и доказательства уровня 4

tests/level4_resilience.py выполняет реальные управляемые сбои:

  1. создаёт и скачивает три настоящих варианта, проверяет MIME, dimensions, size и SHA-256;
  2. создаёт marker в dispatcher, после DB commit процесс делает os.Exit(87) до publish; restart восстанавливает ту же outbox-job;
  3. создаёт marker в worker, процесс делает os.Exit(86) после всех S3 writes, но до result commit/ack; lease принудительно истекает, reaper выполняет redelivery;
  4. подменяет trusted SHA-256 и доказывает permanent invalid_image на attempt 1;
  5. делает staging временно недоступным, получает четыре retry + финальный attempt 5;
  6. находит job через jobctl list-failed, восстанавливает staging и делает явный replay;
  7. повторный replay уже succeeded-job отклоняется;
  8. проверяет ровно три variant rows и staging_key IS NULL.

Фактический итог:

PASS: level-4 variants, outbox crash recovery, lease recovery, backoff/failed registry and safe replay verified.

Исследование уровня 5 — трек 2

Гипотеза

Versioned keys и проверка активной версии во всех DB-переходах обеспечивают идемпотентный итог при at-least-once доставке: подтверждённая работа не теряется при crash до/после side effect, а дубликат, reorder и старая job после v2 не меняют новый результат.

Методика

tests/level5_idempotency.py автоматически выполняет четыре группы воздействий:

  1. crash до первого object write (os.Exit(85)), проверка отсутствия final original, принудительное истечение lease и восстановление v1;
  2. crash после object writes до result COMMIT/ACK (os.Exit(86)), upgrade processing v1→v2 и проверка v1=superseded;
  3. завершение v1, upgrade v2 и сравнение трёх SHA-256 каждой версии;
  4. два дубля v2 и затем reorder устаревшего v1-сообщения после v2.

До воздействия фиксируются active version, job states, variant hashes и original SHA-256. После воздействия проверяются ready:2, неизменность v2/original, шесть исторических variant rows для завершённых v1+v2, отсутствие лишних строк и пустая очередь.

Результат

PASS: pipeline v1/v2 history, crash before/after side effect,
superseded in-flight work, duplicate and reordered stale deliveries verified.

Гипотеза подтверждена в заявленной модели отказов. Подробные команды, sample UUID/хеши, инварианты и ограничения сохранены в evidence/lab5-grade5.md.

Это не exactly-once: RabbitMQ физически может доставить сообщение повторно, publisher может повторить publish после неясного confirm, а worker — повторить S3 write после смерти до ACK. Доказан идемпотентный effectively-once результат: только активная версия может атомарно опубликовать metadata, а versioned keys изолируют side effects.

Таблица проверок

Все результаты ниже повторно получены 2026-11-08 на локальном WSL2/Docker Compose стенде после чистой пересборки образов и финального аудита.

Критерий Команда/сценарий Наблюдаемый результат
Contract/OpenAPI make check, make validate PASS
Public API make test PASS
Уровень 3 make test-async-resilience durability, duplicate, bounded failed — PASS
Уровень 5, трек 2 make test-level5-idempotency v1/v2, crash before/after side effect, duplicate, reorder, stale-after-new — PASS
Три level-4 variants make test-level4-resilience thumbnail 256×160, crop 128×128, optimized WebP 320×200 — PASS
COMMIT → publish crash dispatcher fault marker один job, restart, publish и ready — PASS
S3 writes → commit/ack crash worker fault marker + lease expiry lease_recovered, ready, ровно 3 variants — PASS
Permanent/transient SHA mismatch / missing staging attempt 1 invalid_image / attempt 5 retry_exhausted — PASS
Failed registry/replay jobctl list-failed/replay replay_count=1; replay succeeded-job отклонён
Staging cleanup integration + cleaner_test.go ready удалён; active/recent сохранены — PASS
EXIF/alpha/no-upscale processor_test.go orientation, white JPEG background, WebP alpha, metadata stripping — PASS
Unit/static go test -count=1 ./..., go test -race -count=1 ./..., go vet ./..., go build ./... PASS
Go hygiene gofmt, go mod verify, go mod tidy -diff, git diff --check PASS, изменений/ошибок нет
Frontend чистый docker compose build --no-cache frontend 1/1 Vitest, TypeScript и Vite production build — PASS; 0 npm vulnerabilities
Persistence make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS
API failover make test-failover ACTION_SCRIPT=scripts/stop-one.sh 142 writes, 0 failures, recovery 2.757 s
Boundaries make test-attachment-boundaries 10 MiB/40M px accepted; excess/corruption rejected — PASS
API memory make test-attachment-memory 12/12, 2 replicas; peaks 28,531,752 / 32,516,341 bytes
MinIO policy make test-minio-policy least privilege и anonymous GET denied — PASS
MinIO outage make test-storage-outage readiness 503 2.003 s; upload 503 5.007 s; original preserved
Reconciler make test-reconcile 4 fixture-проблемы; apply удалил 2 объекта и пометил 1 attachment; повтор 0 mutations; reference protected — PASS
Reconciler scale make test-reconcile-scale 100/1000 orphan objects; traversal 33/46 ms — PASS
Fresh migrations одноразовый чистый PostgreSQL + migrations up версии 1→6 применены; version=6, dirty=false — PASS
Изолированный чистый стенд новый Compose project/volumes, порт 18080 smoke + уровни 3/4/5 + reconciler — PASS; после аудита временные volumes удалены
Secrets Git ignore + exact-value scan локальных password/URL/key .env, secrets/, .venv не входят в Git; совпадений чувствительных значений нет
Stale messages memory cleanup + queue inspection messages_ready=0, messages_unacknowledged=0
Compose docker compose --env-file .env config --quiet exit 0

Подробные raw summaries сохранены в evidence/lab5-grade4.md и evidence/lab5-grade5.md.

Повторный предсдаточный аудит 2026-11-08

Аудит обнаружил и устранил две связанные регрессии совместимости lab4→lab5 в служебном reconciler:

  1. старая fixture использовала больше не допустимый статус pending, а reconciler через source-compatible alias мог считать давно стоящий queued устаревшим и ошибочно переводить его в failed;
  2. inventory ownership учитывал только attachments.object_key, поэтому versioned variants и staging могли выглядеть как orphan objects.

Текущая реализация не изменяет queued/processing по одному возрасту, а как принадлежащие attachment учитывает final original, ненулевой staging_key и все ключи из attachment_variants. Unit-тест отдельно фиксирует сохранность старых активных attachment/staging, integration-тест проверяет dry-run/apply/repeat на реальных PostgreSQL и MinIO, а scale-тест повторяет обход на 100 и 1000 объектах.

Финальное состояние отдельного чистого Compose-проекта после всех намеренных crash/restart сценариев и до удаления его временных volumes:

  • обе API-реплики, PostgreSQL, Redis, MinIO, RabbitMQ, frontend и load balancer healthy; migration/bootstrap завершились с exit 0;
  • schema migration 6, dirty=false;
  • jobs: failed=2, succeeded=10, superseded=1, активных queued/processing=0;
  • variant metadata: v1=24, v2=6;
  • RabbitMQ messages_ready=0, messages_unacknowledged=0;
  • у девяти ready attachment нет staging; два failed staging сохранены намеренно до retention/replay;
  • /health/ready возвращает 200 {"status":"ok"}, frontend / возвращает 200.

На основном стенде после такого же прогона fault-marker files отсутствуют, а за минуту после стабилизации новых panic/fatal/error/warn в логах не появилось. Временный чистый Compose-проект mtusi2026lab5audit1108 и только его изолированные volumes после снятия результатов удалены.

Ограничения

Уровень 4 и выбранный трек 5 полностью реализованы.

  • Поддержаны pipeline v1 и v2; произвольный registry версий и профилей не реализован.
  • Upgrade является операторской командой, а не публичным пользовательским API.
  • Старые versioned variant-объекты сохраняются для аудита; lifecycle архивных версий не реализован.
  • Lease фиксированный и длиннее timeout; heartbeat-продление для динамических SLA отсутствует.
  • Failed registry находится в PostgreSQL, а не отдельной broker DLQ, чтобы сохранить атомарную связь с attachment и audit.
  • At-least-once плюс идемпотентный эффект не является exactly-once delivery.
  • Эксперимент выполнен на одном Docker-host и не покрывает потерю host или volumes PostgreSQL/MinIO.