Files
mtusi2026lab5/REPORT.md
T
Alexey Bodanyuk 77a50af326 lab5: доказательства из чистого clone, REPORT с результатами трека 2, текст PR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

collect_evidence на новом clone (новые secrets, пустые volumes): make check/validate/test,
test-persistence, test-failover (обе реплики), сценарий защиты, свои тесты 377 passed,
матрица трека 2 12/12 без нарушений, аудит ok (522 объекта, SHA-256). Исправлен порядок
шагов сценария «reorder версий» (не запускать сервис с обычной конфигурацией между шагами).
2026-10-31 17:59:42 +03:00

27 KiB
Raw Blame History

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

  • Автор, группа: Боданюк Алексей, БВТ2302
  • Целевая оценка; трек 5: 5, трек 2 «Доказанная идемпотентность pipeline»
  • Commit/PR: ветка solution/bvt2302-bodanyuk; PR «ЛР 5 — БВТ2302 — Боданюк — на 5» (ссылка после публикации)
  • Источники, библиотеки, ИИ: Python 3.13, Starlette, uvicorn, psycopg 3, redis-py, argon2-cffi, aiobotocore (из ЛР 2–4); новое: aio-pika 9.6.2 (AMQP), Pillow 12.3.0 (варианты, только в worker). Документация: RabbitMQ reliability, confirms, quorum queues, AWS «Exponential Backoff And Jitter». Код, тесты и документы написаны с помощью ИИ-ассистента (Claude); архитектурные решения разобраны и объяснимы автором (см. docs/DEFENSE.md).

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

Версии (всё по тегу и digest, см. compose.yaml): Python 3.13.16-slim-bookworm, PostgreSQL 18.6, Valkey 8.1.3, SeaweedFS 4.46, RabbitMQ 4.3.7-alpine, HAProxy 3.2.26. Python-пакеты — requirements.txt с sha256-хешами (pip install --require-hashes --no-deps).

Prerequisites: Docker с Compose v2, Python 3.12+, Git; на Windows — docs/WINDOWS.md.

git clone <fork> mtusi2026lab5 && cd mtusi2026lab5 && git checkout solution/bvt2302-bodanyuk
python3 scripts/init_secrets.py            # ./secrets: пароли БД/Valkey, 4 пары S3, пользователи RabbitMQ (хеши), URL брокера
cp .env.example .env
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait   # migrate и s3-init — один раз, exit 0; остальные healthy
make check test                            # Windows: $env:PYTHONUTF8="1"; make ... PYTHON=python
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh && make restore
python3 -m venv .venv && .venv/bin/pip install --require-hashes --no-deps -r requirements.txt && .venv/bin/pip install -r requirements-test.txt
.venv/bin/python scripts/demo_pipeline.py  # сценарий защиты, шаги 2-3
.venv/bin/python -m pytest student-tests -v
.venv/bin/python bench/pipeline_faults.py --output evidence/track2
make audit                                 # инварианты, read-only

Всё это одной командой на чистом clone: python scripts/collect_evidence.py (вывод — в evidence/). Действий оператора нет. Безопасная остановка: docker compose down (volumes остаются). Намеренное удаление учебных данных: docker compose down -v и удалить ./secrets.

Архитектура и решения

client ─▶ lb (HAProxy) ─▶ api ×2 ──▶ postgres (метаданные, jobs, outbox, попытки, аудит)  [data]
                               ├──▶ valkey (сессии)                                       [data]
                               └──▶ s3: messenger-staging (Write) / messenger-attachments (Read)  [storage]
relay ──▶ postgres (outbox, reaper) ──▶ broker (RabbitMQ, quorum queue + DLQ)             [data, queue]
worker ◀── broker; ──▶ postgres; ──▶ s3 (Read/Write оба bucket)                            [data, storage, queue]
  • Источник истины — PostgreSQL, включая работу: состояние, попытки, lease, время повтора, реестр failed. Брокер доставляет только job_id; ack — после COMMIT результата. Подробно — docs/PIPELINE.md; схема — docs/DATA_MODEL.md.
  • Транзакционные границы. Upload: pending → PUT staging → одна транзакция queued + jobs + outbox → 202. Результат: одна транзакция attachment_variants ×3 + attachments ready с проверкой lease_token → ack.
  • API не связан с брокером (нет сети queue, нет учётных данных). Недоступность worker/брокера не делает resize синхронным и не ломает upload.
  • Перенесено из lab4 без изменений (коммит 5112be8): API, сессии, идемпотентность сообщений, HAProxy с активной readiness, лимиты загрузки, PNG-валидатор и djpeg -strict, janitor pending, graceful shutdown, тесты.
  • Изменено: upload 201 → 202; GET метаданных видит queued/processing/failed; content → 409 до ready, варианты thumbnail/crop/optimized; к сообщению можно прикрепить queued/processing (post_message_v3), failed → 409; S3 разделён на два bucket и четыре identity; restart-хук перезапускает и broker/relay/worker.
  • Убрано: reconciler lab4 (трек прошлой лабы, не обязательный минимум). В lab5 мусор находится по журналу job_attempts.planned_keys без права List; аудит messenger.audit проверяет оба bucket read-only-ключом. Удаление файлов reconciler попало в коммит a633949, а не в bc32a50, где об этом сказано, — ошибка при разбиении коммитов, историю не переписывал.
  • Ограничения доступа. S3: api — Write staging + Read final; worker — Read/Write оба; auditor — Read+List; admin — только s3-init. RabbitMQ: relay — только write в exchange messenger.jobs, worker — только read очереди, configure ни у кого; guest нет; management UI и Prometheus выключены. Проверяется s3-init при каждом старте и тестом test_compose_policy_limits_ports_secrets_images.

Соответствие .env.example

Переменная Значение Где
BROKER_URL_FILE /run/secrets/broker_url relay и worker, у каждого свой пользователь RabbitMQ
S3_STAGING_BUCKET messenger-staging api, worker, s3-init, auditor
WORKER_CONCURRENCY 2 prefetch и число дочерних процессов worker
JOB_MAX_ATTEMPTS 5 claim-ов на задание (пишется в задание при создании)
JOB_TIMEOUT_SECONDS 60 потолок одной попытки (kill процесса, конец продления lease)
JOB_LEASE_SECONDS 30 lease, heartbeat каждые 10 с
JOB_RETRY_BASE_SECONDS / _MAX_ 2 / 60 full jitter
STAGING_RETENTION_SECONDS 86400 хранение staging у failed для replay (у ready удаляется сразу)
ORPHAN_GRACE_SECONDS 600 удаление объектов неуспешных попыток
IMAGE_MAX_MEMORY_MB 768 RLIMIT_AS дочернего процесса
PIPELINE_VERSION 1 версия заданий новых загрузок (1, 2, 3 в pipeline.py)
API_/RELAY_/WORKER_FAULT_POINTS пусто внедрение отказов только для экспериментов
MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS 10485760, 40000000 API (до чтения тела) и worker (до скачивания/декодирования)

Доказательства критериев

Все файлы — из прогона scripts/collect_evidence.py на чистом clone (новые secrets, пустые volumes), см. раздел «Финальный прогон».

Критерий README Команда/сценарий Наблюдаемый результат Файл
Публичный smoke make check validate test PASS ×3: 202 → ready, JPEG 256×160 make-check-validate-test.txt
3: минимум lab4 сохранён, 201 → 202 pytest student-tests (test_api, test_attachments, test_idempotency, test_balancing, test_sessions, test_failures) 377 passed; 415 на все кейсы рецензий (PNG фильтр 5/0xff, IDAT не zlib, JPEG 27 байт, SOS не из SOF) student-tests.txt
3: 202 только после устойчивого приёма; остановка API не теряет test_consistency (after_s3_put, after_enqueue_commit), demo окно «после staging» — невидимый pending, убран janitor; после COMMIT — ready student-tests.txt
3: отдельные broker и worker, durable, ack после эффекта compose, rabbitmqctl list_queues; test_worker_crash_after_commit… quorum queue durable; redelivery → noop_finished clean-clone.txt, student-tests.txt
3: worker недоступен → API не делает resize test_worker_stopped…, demo 202 queued, content 409, сообщения 201 demo-pipeline.txt
3: состояния queued/processing/ready/failed, thumbnail по контракту test_pipeline_flow (check_variants) реальные размеры через Pillow, sha256 = метаданные, оригинал побайтно student-tests.txt
3: ограниченный retry, failed + error_code; повтор не плодит варианты test_retry_exhausted…, test_duplicate… 5 попыток → retry_exhausted; дубли → 1 набор student-tests.txt
3: демонстрация stop worker → 202 → сообщение → restart API (+broker) → ready scripts/demo_pipeline.py очередь messages=1 до и после рестарта брокера, ready, одна попытка demo-pipeline.txt
Persistence / failover (публичные) make test-persistence, make test-failover PASS, состояния контейнеров до/после test-persistence.txt, test-failover.txt
4: crop 128 и WebP 1280, параметры unit test_pipeline + check_variants геометрия, EXIF, alpha, без метаданных — PIPELINE.md student-tests.txt
4: лимиты bytes/пикселей/времени/памяти worker test_memory_and_time_limits_of_the_worker, test_exactly_40_megapixels… 40 Мпикс при 200 МБ → image_too_large; 3 с → processing_timeout; 40 Мпикс в 768 МБ → ready student-tests.txt
4: outbox; crash между COMMIT и publish test_broker_down…, test_relay_down…, test_crash_after_publish… строка outbox ждёт, публикуется без ручных действий student-tests.txt
4: backoff с jitter, постоянные/временные test_transient_errors…, test_permanent_error… задержки в [0, base·2^(n−1)], invalid_image — 1 попытка student-tests.txt
4: DLQ/реестр failed, безопасный replay jobctl list-failed/replay, test_bad_message… replay → ready; replay готового → already_ready; плохое сообщение → DLQ student-tests.txt
4: crash после записи объекта до ack test_worker_crash_after_s3_write…, …after_commit… один опубликованный набор, мусор попытки 1 удалён student-tests.txt
4: lease зависшего processing, prefetch, очистка staging test_hung_worker… (docker pause), test_concurrency…, test_queued_staging…, test_cleanup_racing… попытки [abandoned, succeeded]; ≤2 processing; staging queued не удаляется, CHECK отвергает student-tests.txt
5, трек 2 bench/pipeline_faults.py, make audit 12/12 сценариев, 0 нарушений, аудит ok evidence/track2/, track2-runs.txt

Эксперименты и отказы

Трек 2: доказанная идемпотентность versioned pipeline

Гипотеза. При at-least-once доставке, дублях и переупорядочивании сообщений, crash worker до/после побочного эффекта и устаревших заданиях старой версии pipeline: (H1) ни одна принятая 202 работа не теряется; (H2) каждый эффект (attachment, version, variant) опубликован ровно один раз; (H3) опубликованная версия только растёт, ready не откатывается; (H4) мусор прерванных попыток удаляется, опубликованное не удаляется никогда.

Механизм. Ключ эффекта — PK attachment_variants; ключи объектов включают токен попытки; fencing lease_token при каждом COMMIT; монотонный published_version; claim по состоянию задания в БД; уборка только по planned_keys неуспешных попыток под блокировкой.

Методика (bench/pipeline_faults.py). Для каждого сценария пересоздаётся один сервис с FAULT_POINTS (реальные пути кода, реальный os._exit, реальный docker pause), N загрузок через LB, затем читаются факты из PostgreSQL и S3 (List auditor-ключом), а в конце аудит I1–I7 с проверкой SHA-256 всех опубликованных объектов по всему стенду.

Сценарий Внедрение
baseline —
дубль relay публикует каждое сообщение дважды
дубль + reorder дважды и в обратном порядке пачки
crash relay после confirm до отметки os._exit relay
crash worker до побочного эффекта os._exit после claim
crash worker после S3 до COMMIT os._exit после PUT объектов
crash worker после COMMIT до ack os._exit после COMMIT
временные ошибки 2 неудачные попытки
2 worker + дубль конкурирующие потребители
устаревшая версия reprocess v2 (медленный) и v3 одновременно; затем вручную опубликованный дубль задания v1
reorder версий в очереди v2 и v3 в outbox, relay публикует в обратном порядке, 1 worker
зависший worker 2 worker, docker pause владельца lease

Результаты (чистый clone, 2026-10-31 14:48–14:57 UTC, 5 загрузок на «плоский» сценарий; summary.txt, подробно — summary.json):

Сценарий Загрузок ready claim-ов Нарушений Последовательность событий задания
baseline 5 5 5 0 created › claimed › succeeded
дубль publish 5 5 5 0 то же: второе сообщение — noop_finished
дубль + обратный порядок 5 5 5 0 то же
crash relay после confirm 5 5 5 0 created › claimed › fault_injected › succeeded
crash worker после claim 5 5 14 0 claimed › fault_injected › lease_expired › claimed › succeeded (*)
crash worker после S3, до COMMIT 5 5 10 0 claimed › fault_injected › lease_expired › claimed › succeeded
crash worker после COMMIT, до ack 5 5 5 0 claimed › succeeded › fault_injected (redelivery = no-op)
2 временные ошибки 5 5 15 0 3 claim-а на загрузку, ровно как задано
2 worker + дубль 5 5 5 0 один claim при конкурирующих потребителях
устаревшая версия 1 — — 0 v1 succeeded, v2 (медленная) superseded при COMMIT, v3 succeeded; статус всё время ready; ручной дубль задания v1 — no-op
reorder версий в очереди 1 — 2 0 v3 опубликована первой, v2 superseded при claim без работы
зависший worker (docker pause) 1 — 2 0 claimed › lease_expired › claimed › succeeded; ожившая попытка fenced
аудит всего стенда после матрицы 0 ok=True, 522 опубликованных объекта, SHA-256 сверены, final=523 (+sentinel)

(*) claim-ов больше, чем 2 на загрузку: os._exit при одном задании убивает весь процесс, а с ним и соседнюю попытку другого задания (prefetch 2). Ей тоже приходится ждать истечения lease. Это и есть «crash до побочного эффекта»: лишние claim-ы ничего не публикуют, и ни в одном сценарии нет второго набора вариантов или объектов (столбец «Нарушений» — проверки H2/H4 по БД и S3).

Вывод. H1–H4 подтверждены на всех 12 сценариях: 0 нарушений по сценарным проверкам и по аудиту I1–I7. Время до ready при отказах определяется lease (6 с в эксперименте) + интервалом reaper (5 с): 15–22 с против ~2 с без отказов.

Ограничения эксперимента. Один прогон матрицы на 5 загрузок (плюс прогоны тех же сценариев в student-tests и отладочный прогон на 3 загрузки — тоже 0 нарушений). Это доказательство на конечном наборе чередований, а не формальная верификация. Отказы внедряются в заранее выбранных точках кода, а не в случайные моменты. Один Docker-хост.

Почему это не exactly-once. Доставка остаётся at-least-once: в сценариях дубля в очереди физически два сообщения, а у зависшего worker вычисление выполнялось дважды (попытки abandoned и succeeded). Exactly-once — только у видимого эффекта, за счёт ключа эффекта, fencing и монотонной версии. Чего нет: (1) защиты от двух независимых сред с разными БД; (2) гарантии при потере диска одного Docker-хоста (quorum queue и PostgreSQL на одном узле); (3) удаления опубликованных вариантов старых версий — они остаются (rollback-кандидаты), удаляются только неопубликованные.

Отказы

Воздействие Что ожидаем Что наблюдали Восстановление / потеря
worker остановлен, upload 202, content 409, сообщения работают так и есть после старта worker → ready, 0 потерь
restart API + broker с volumes сообщение остаётся в quorum queue messages=1 до и после 0 потерь
broker остановлен upload 202, outbox ждёт published=False, текст работает relay публикует после возврата брокера
relay остановлен outbox ждёт так и есть ready после старта
crash relay после confirm дубль в очереди один claim, один набор 0 дублей эффекта
crash worker после claim / S3 / COMMIT lease → reaper → попытка 2; либо no-op [abandoned, succeeded]; мусор удалён lease 6 с в тесте (30 с по умолчанию) + ≤5 с reaper
docker pause worker с lease второй worker публикует, первый fenced так и есть ≤ lease + 5 с + AMQP heartbeat
5× временная ошибка failed/retry_exhausted → replay → ready так и есть replay оператора
уборка vs replay (пауза в уборке) staging не удалён ready, staging удалён только после ready —
S3 остановлен/заморожен (lab4) readiness 503, upload 503 < 8 с, текст работает так и есть файлы целы

Дефекты, найденные в ходе работы и исправленные:

  1. После рестарта брокера worker оставался без consumer, а healthcheck показывал healthy; relay падал на ChannelInvalidStateError. Причина: aio-pika не выставляет is_closed при закрытии соединения сервером. Исправлено (1d37fd0): close_callbacks, heartbeat-файл только при живом consumer.
  2. Внедрённый crash worker срабатывал на каждой попытке, а не один раз на задание. Исправлено там же.
  3. Аудит ошибочно требовал объект staging у pending (PUT мог не пройти). Исправлен инвариант I5.

Окружение и лимиты

Ноутбук: AMD Ryzen 5 3400G (4 ядра / 8 потоков), 29,9 ГБ RAM, Windows 10 Enterprise 19045, Docker Desktop 29.8.0 (VM: 8 CPU, 15,7 ГБ). Лимиты контейнеров (фактические, docker inspect в clean-clone.txt): api 1 CPU / 512m ×2, worker 2 CPU / 1536m (без swap), broker 1 CPU / 512m, relay 0,5 / 256m, postgres 2 / 1g, s3 1 / 1g, valkey 0,5 / 256m, lb 1 / 128m, migrate/s3-init 0,5 / 256m, auditor 1 / 256m, jobctl 0,5 / 128m. Нагрузочных выводов о производительности в этой лабе не делается (трек 2 — про корректность); tests/load.py приложен как контроль регрессии lab3.

Финальный прогон

python scripts/collect_evidence.py в новой папке (git clone ветки, commit cf6e929): новые secrets, пустые volumes (стенд разработки удалён down -v), образы приложения собраны заново (слои базовых образов из кэша Docker). Все шаги exit 0:

Файл Что внутри
clean-clone.txt init_secrets, compose config, up --build --wait, migrate (0001–0005), s3-init (вердикты прав), пользователи и права RabbitMQ, очереди, лимиты docker inspect, версии
make-check-validate-test.txt make check PASS, make validate PASS, make test PASS lab5
test-persistence.txt PASS; состояния контейнеров до/после (новые pid у lb, api, relay, worker, postgres, valkey, s3, broker)
test-failover.txt PASS дважды, остановлены обе реплики по очереди
demo-pipeline.txt сценарий защиты шаги 2–3, очередь messages=1 до и после рестарта брокера, ready, JPEG 256×160
student-tests.txt 377 passed, 4 skipped (skipped — unit-тесты djpeg, которого нет на Windows-хосте; те же случаи проходят против стенда), 25 мин
track2-runs.txt, track2/ матрица трека 2, аудит --verify-checksums, jobctl stats (outbox пуст), tests/load.py
load.json контроль регрессии lab3: 183 успешных RPS, 0 ошибок, p95 44 мс (4 клиента, 30 с; не сравнивается с lab3 — другой стенд)

Свап: у api и worker memswap = memory (без swap). У инфраструктурных контейнеров остался умолчательный swap Docker (= 2 × memory) — видно в docker inspect, для выводов этой лабы не важно.

Ограничения и следующие шаги

  • Один Docker-хост: quorum queue на одном узле (без репликации), PostgreSQL один. «Устойчиво» = переживает рестарт процессов/контейнеров с volumes.
  • SeaweedFS подтверждает PUT без явного fsync каждой записи; потеря питания хоста — вне модели угроз.
  • Опубликованные варианты старых версий не удаляются; квоты на число версий нет.
  • Колонки карантина lab4 (lost_at) сохранены, но ничем не выставляются (reconciler удалён).
  • Объект, записанный замороженной попыткой после её уборки (пауза дольше ORPHAN_GRACE_SECONDS), станет мусором; аудит покажет его как leaked_object. Это не потеря: опубликованное не задевается.
  • Следующие шаги: трассировка (traceparent в сообщении уже предусмотрен схемой) — lab6.