Files
mtusi2026lab5/REPORT.md
T

17 KiB
Raw Blame History

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

  • Автор, группа: Казанцева Виктория / БПИ2301
  • Целевая оценка: 5. Трек 2 — доказанная идемпотентность versioned pipeline
  • Commit/PR: mtusi2026/mtusi2026lab5#31
  • Дата прогона: 6 ноября 2026, хост Windows 10, Docker 29.2.1, Compose v5.1.0, Python 3.11 (клиент) и Python 3.12.8 в образе
  • Источники и библиотеки: контракт репозитория, документация RabbitMQ; FastAPI, uvicorn, psycopg, argon2-cffi, boto3, pika, Pillow. Секреты в отчёт не копировались

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

Нужны Docker Compose и Python 3.9+. На Windows публичные тесты читают JSON без явной кодировки, поэтому перед ними нужен PYTHONUTF8=1.

python scripts/bootstrap.py
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build

bootstrap.py один раз создаёт локальный .env со случайными паролями и не печатает их. Повторный запуск существующий файл не перезаписывает. Миграции применяет сам API и worker при старте (migrations/001_init.sql, advisory lock). Отдельной ручной миграции нет. Готовность: GET http://127.0.0.1:8080/health/ready возвращает 200. Брокер и worker для ready не нужны: намерение лежит в outbox.

python scripts/check_contract.py
python tests/smoke.py --base-url http://localhost:8080
python student_tests/test_images.py
python student_tests/run_grade.py
python student_tests/run_hooks.py

На Linux те же команды через make check, make test, и после chmod +x scripts/restart.sh scripts/stop-one.sh:

make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
sh scripts/start-apis.sh

Остановка без удаления данных: docker compose --env-file .env stop. Удаление учебных volumes: docker compose --env-file .env down -v.

Архитектура

Публичный вход только у nginx (127.0.0.1:8080 в этом прогоне был опубликован как 8080:8080). За ним две реплики API, api-1 и api-2. Тяжёлую обработку делает отдельный процесс python -m app.worker. Состояние: PostgreSQL 16.8, объектное хранилище, RabbitMQ 3.13.7. Volumes: pgdata, miniodata, rabbitdata.

Официальные образы minio/minio и quay.io/minio/minio на момент сборки анонимно не скачиваются. Объектное хранилище — совместимый образ pgsty/silo:RELEASE.2026-10-26T00-00-00Z. Клиент говорит с ним по S3 API (boto3, path-style). Бакет создаёт одноразовый minio-init.

Приём файла:

  1. Проверка участника чата, лимита очереди, Content-Type, magic bytes, размера и числа пикселей по заголовку, до полного decode.
  2. Оригинал целиком пишется в staging/{attachment_id}.
  3. В одной транзакции создаются строка attachment со статусом queued, job и строка outbox.
  4. Ответ 202 — это снимок, зафиксированный до публикации. Даже если worker успел раньше, клиент получает queued.
  5. Relay API и worker публикует outbox после COMMIT. Подтверждение брокера (publisher confirm, delivery_mode=2, mandatory) не заменяет consumer ack.

Worker подтверждает сообщение только после устойчивого эффекта: объект в originals/{id}, варианты variants/{id}/v{version}/{name}, commit в PostgreSQL. Prefetch каждого потребителя равен 1, потребителей WORKER_CONCURRENCY (в .env — 2). Память контейнера worker ограничена 512 MiB, MALLOC_ARENA_MAX=2. Это не жёсткий RLIMIT_AS.

Ключ эффекта: (attachment_id, pipeline_version, variant). Повтор той же версии не создаёт второй набор. Более старая версия не затирает больший ready_pipeline_version. Если новая версия упала, публичный статус возвращается к последней успешной версии.

Соответствие .env.example: DATABASE_URL и BROKER_URL заданы прямо в локальном .env, а не через *_FILE; код принимает оба способа. SESSION_TTL_SECONDS=3600, IDEMPOTENCY_TTL_SECONDS=86400, MAX_UPLOAD_BYTES=10485760, MAX_IMAGE_PIXELS=40000000, JOB_MAX_ATTEMPTS=5, JOB_TIMEOUT_SECONDS=60, JOB_BACKOFF_BASE_SECONDS=0.4, JOB_BACKOFF_CAP_SECONDS=8, STAGING_RETENTION_SECONDS=86400, MAX_QUEUED_JOBS=500. Короткий backoff нужен, чтобы исчерпание пяти попыток укладывалось в окно теста. Сессии и идемпотентность хранятся в PostgreSQL, отдельный Redis не используется.

Pipeline v1: JPEG thumbnail и crop quality 85, WebP quality 80 method 6. Pipeline v2 меняет только качество (JPEG 60/70, WebP 50 method 4), геометрия та же. EXIF orientation применяется до кодирования, альфа кладётся на белый, метаданные в варианты не копируются. Thumbnail вписывается в 256×256 без увеличения, crop — центр 128×128 с увеличением, optimized вписывается в 1280×1280 без увеличения.

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

Критерий Команда Наблюдение Файл
Контракт skeleton python scripts/check_contract.py PASS: offline skeleton structure... stdout
Геометрия вариантов python student_tests/test_images.py PASS: image contract geometry stdout
Публичный smoke, upload 202 и JPEG thumbnail python tests/smoke.py --base-url http://localhost:8080 PASS: lab5 public API scenario... Два прогона: до сценариев отказов и после рестарта stdout
Compose docker compose --env-file .env config --quiet код 0 —
Уровень 3: worker остановлен, 202, content 409, чат жив, рестарт API и RabbitMQ, тот же attachment ready python student_tests/run_grade.py очередь до рестарта 1 и после 1; attachment 7e2aaf32-e234-4568-8018-0aec26ac0308 evidence/grade5-track2.json
Уровень 4: crop, WebP, лимиты, outbox, retry, DLQ, replay, crash до ack тот же прогон все сценарии pass, см. идентификаторы ниже evidence/grade5-track2.json
Трек 2 тот же прогон versioned pipeline, reorder, stale job evidence/grade5-track2.json
Hook рестарта всех хранилищ python student_tests/run_hooks.py StartedAt всех семи контейнеров сменился; сообщение c7f0d384-570b-451d-aff3-99fe85f74841 и объект 90c60051-aa82-4dea-930a-785505bf7770 читаются прежним токеном stdout
Отказ одной реплики тот же прогон api-1 восстановился за 1.563 с, 23 записи, 0 ошибок; api-2 за 2.578 с, 25 записей, 2 ошибки переходного периода. Остановленная реплика не была в хвосте ответов stdout

Идентификаторы трека, без токенов:

  • outbox при паузе публикации: attachment d29ac3f0-963c-4579-b7ca-9470e42d90b3, тот же job a457806d-b295-43ee-a671-2fa36f24388a, затем ready
  • постоянная ошибка и безопасный replay: attachment f184e530-2798-4d1a-9a0d-fbf0ceff4d0a, job f52005ae-a113-47bf-879a-f7b820f74591; второй replay — already_ready
  • одна временная ошибка: attachment dd1faa48-e8cf-4560-a537-f2f170717b28, attempt 2
  • пять временных ошибок: attachment 7c532988-a75e-4967-9eec-0213bd37fdeb, retry_exhausted, затем явный replay до ready
  • дубль доставки: attachment 76144ebf-bc05-41a9-bd54-e94459b2e79a, три варианта v1, повторный SHA тот же
  • crash до side effect: 18e6a58f-4bbd-47d9-b9ac-d0b6402cb46f
  • crash после записи объекта: 67349346-ef4b-43ce-8388-2dfe0a8df36d
  • crash после commit до ack: 7ce2d67e-c042-4c49-9747-4dc0c1117250
  • устаревшая v1 после готовой v2: attachment b7eee35e-0d2d-4cb1-9143-7af26c55a9a0, новый job bc8bfec7-1460-4f0f-a9aa-d62e2cef1bcf
  • reorder: attachment 18c8cf9d-1a82-452d-b0ee-9028873859fc, старый job стал superseded, публичный результат — v2

Рестарт hook, StartedAt до и после: postgres 18:56:06Z → 18:57:32Z, minio 18:56:05Z → 18:57:31Z, rabbitmq 18:56:06Z → 18:57:32Z, api-1/api-2, worker и nginx тоже сменили время старта. Volumes не удалялись.

Публичный tests/resilience.py на этом Windows-хосте не смог запустить .sh: WinError 193. Скрипты оставлены POSIX и с LF. student_tests/run_hooks.py выполняет те же docker compose restart и docker stop по метке lab.instance_id. На Linux оценщик запускает сами scripts/restart.sh и scripts/stop-one.sh.

Трек 2

Гипотеза: доставки at-least-once достаточно, если эффект именуется (attachment_id, pipeline_version, variant), а публичный результат двигается только вперёд по ready_pipeline_version. Подтверждённый результат не теряется, старая версия не затирает новую.

Методика: одноразовые режимы в runtime_control — пауза outbox, duplicate, before_effect, after_s3, after_commit, повторная доставка того же job_id, новая версия pipeline и публикация старого сообщения после неё. Проверялись статус, число строк вариантов, SHA-256, audit и ready_pipeline_version. Новое задание руками не создавалось. Объекты одной версии пишутся только если ключа ещё нет; вставка варианта — ON CONFLICT DO NOTHING.

Результат: все перечисленные сценарии завершились pass за один прогон run_grade.py (около 67 с). После crash worker сам поднялся (restart: on-failure, выход 75). docker stop выходит 0 и оставляет worker остановленным.

Почему это не exactly-once. Брокер может доставить сообщение дважды, relay может опубликовать строку повторно, если процесс умер после confirm и до отметки published_at. Идемпотентность находится в ключе эффекта и в статусе job, а не в транспорте. Повтор успешной job — no-op и ack, а не второе исполнение. Exactly-once доставки нет: есть повторная доставка и однократный видимый эффект.

Ограничения измерения. Инъекция кооперативная: worker читает флаг и вызывает os._exit в названной точке, это не случайный обрыв на произвольной инструкции. Жёсткий kill посреди записи объекта опирается на lease 60 с и на сравнение уже записанных байтов. Lease не продлевается во время работы; нормальная работа обязана уложиться в JOB_TIMEOUT_SECONDS, тем же пределом ограничен decode. Два перекрывающихся исполнителя одной версии не создают второй набор ключей, но лишний decode возможен, если lease уже истёк. Трек 1 (сравнение prefetch под нагрузкой) не выполнялся.

Отказы

Воздействие Ожидание Наблюдение Восстановление
Worker остановлен, затем рестарт API и RabbitMQ 202, content 409, сообщение чата 201, очередь жива очередь 1 → 1, тот же attachment ready после старта worker, оригинал тот же
Пауза outbox между COMMIT и publish job сохранён, брокер пуст unpublished ≥ 1, глубина очереди 0, тот же job_id ready без нового задания
Постоянная ошибка invalid_image, content и attach 409 так и есть replay того же job до ready; повторный replay не исполняет дубль
Пять временных ошибок retry_exhausted, запись в реестре failed так и есть явный replay до ready
Crash после S3 до commit и после commit до ack тот же результат, три варианта v1 audit fault_after_s3 и fault_after_commit ready без второго набора
Старая версия после новой SHA v2 и ready_pipeline_version=2 сохраняются 6 строк вариантов, публичный набор не откатился старый job superseded или no-op
Рестарт Postgres, Silo, RabbitMQ, API, worker, nginx сессия, сообщение и байты на месте hook и grade-прогон без повторного логина
Остановка одной API-реплики пишет вторая, остановленная не отвечает оба идентификатора проверены отдельно 1.6–2.6 с, реплика остаётся остановленной до compose start

Повторы: задержка min(cap, base * 2^(attempt-1)) * U(0.5, 1.5). Временная ошибка возвращает job в queued и пишет новую строку outbox. Постоянная и исчерпание попыток пишут failed_jobs и копию сообщения в attachment.dlq. Staging готового объекта удаляется после commit; staging failed хранится STAGING_RETENTION_SECONDS, чтобы replay мог его прочитать.

Ограничения

  • Готовность не проверяет RabbitMQ и worker. Это намеренно: принятая работа лежит в PostgreSQL и staging.
  • max_fails=0 у nginx. Иначе один отказ на старте на 3 с выключает оба upstream и даёт 502 «no live upstreams». Мёртвая реплика стоит одной попытки соединения (1 с), затем запрос уходит на живую. Официальный failover-клиент с timeout 2 с это выдержал.
  • Сильный kill -9 внутри lease не мгновенно подхватывается другим worker. Подхват — после JOB_TIMEOUT_SECONDS.
  • Память worker ограничена cgroup, не адресным лимитом процесса. Decode сверх таймаута считается временной ошибкой; поток decode при этом может ещё завершиться в фоне.
  • На этом хосте порт 8080 был занят контейнером mtusi-lb прежнего стенда. Остановлен только он, его volumes не удалялись. Чтобы вернуть старый вход, нужно остановить nginx этой лабораторной и снова запустить mtusi-lb.
  • Операторские маршруты описаны в contracts/extensions.md. contracts/openapi.json и публичные тесты не менялись.