21 KiB
Отчёт — лабораторная 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
- API ограниченно читает максимум 10 MiB, проверяет MIME, полный decode и максимум 40 млн пикселей.
- Проверенный оригинал устойчиво записывается в приватный MinIO staging.
attachments(status=queued)иattachment_jobs(status=queued, attempt=1)фиксируются одной транзакцией PostgreSQL.- Только после успешного 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, attachmentfailed/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 выполняет реальные управляемые сбои:
- создаёт и скачивает три настоящих варианта, проверяет MIME, dimensions, size и SHA-256;
- создаёт marker в dispatcher, после DB commit процесс делает
os.Exit(87)до publish; restart восстанавливает ту же outbox-job; - создаёт marker в worker, процесс делает
os.Exit(86)после всех S3 writes, но до result commit/ack; lease принудительно истекает, reaper выполняет redelivery; - подменяет trusted SHA-256 и доказывает permanent
invalid_imageна attempt 1; - делает staging временно недоступным, получает четыре retry + финальный attempt 5;
- находит job через
jobctl list-failed, восстанавливает staging и делает явный replay; - повторный replay уже succeeded-job отклоняется;
- проверяет ровно три 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 автоматически выполняет четыре группы воздействий:
- crash до первого object write (
os.Exit(85)), проверка отсутствия final original, принудительное истечение lease и восстановление v1; - crash после object writes до result COMMIT/ACK (
os.Exit(86)), upgrade processing v1→v2 и проверкаv1=superseded; - завершение v1, upgrade v2 и сравнение трёх SHA-256 каждой версии;
- два дубля 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:
- старая fixture использовала больше не допустимый статус
pending, а reconciler через source-compatible alias мог считать давно стоящийqueuedустаревшим и ошибочно переводить его вfailed; - 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; - у девяти
readyattachment нет 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.