17 KiB
Отчёт — лабораторная 5
- Автор, группа: Казанцева Виктория / БПИ2301
- Целевая оценка: 5. Трек 2 — доказанная идемпотентность versioned pipeline
- Commit/PR: #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.
Приём файла:
- Проверка участника чата, лимита очереди,
Content-Type, magic bytes, размера и числа пикселей по заголовку, до полного decode. - Оригинал целиком пишется в
staging/{attachment_id}. - В одной транзакции создаются строка attachment со статусом
queued, job и строка outbox. - Ответ 202 — это снимок, зафиксированный до публикации. Даже если worker успел раньше, клиент получает
queued. - 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, тот же joba457806d-b295-43ee-a671-2fa36f24388a, затем ready - постоянная ошибка и безопасный replay: attachment
f184e530-2798-4d1a-9a0d-fbf0ceff4d0a, jobf52005ae-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, новый jobbc8bfec7-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и публичные тесты не менялись.