Files
mtusi2026lab5/REPORT.md

21 KiB
Raw Permalink Blame History

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

  • Автор, группа: Щербацевич Владислав Сергеевич, БПИ2302
  • Целевая оценка; выбранный трек 5, если нужен: 4. Трек 5 не заявляется.
  • Commit/PR: локальная работа, публикация не выполнялась
  • Использованные источники, библиотеки и помощь ИИ: контракт репозитория (contracts/, tests/, README лабораторной), документация RabbitMQ reliability/confirms, Pillow, aio-pika 9.5.5, SQLAlchemy 2, FastAPI. Реализацию очереди, worker, outbox и проверок уровня 4 в этой сессии вёл ассистент Cursor (Grok). Объяснение решения на защите остаётся за автором.

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

Стенд рассчитан на Docker Compose на одном хосте. Проверялось на Windows 10, Docker Desktop 29.6.1, Python 3.13 на хосте (в образе python:3.13.16-slim-bookworm). На Windows перед scripts/check_contract.py нужна переменная PYTHONUTF8=1: иначе чтение openapi.json падает на cp1251. На Linux-проверке преподавателя это не требуется.

Образы закреплены тегом и digest:

Роль Образ
API, worker, relay, gc, migrate python:3.13.16-slim-bookworm@sha256:a1165e272e578941b84abc79e4ab38a0305cd12803a5c4247979ac7655f4d641
PostgreSQL postgres:16.10-bookworm@sha256:38471f330eb885e04de130b768d6db4e10469e2311879c7e5c699f6d2d8a1c74
Redis redis:7.4.6-alpine@sha256:3b73847e72874be07e6657b129a94761662b79bc0f679273757d4218573b2a98
MinIO pgsty/minio:RELEASE.2026-08-04T00-00-00Z@sha256:b6bfe7239bfc83fb90d31612d9704d86039dd714f7904b3f1ad68f211e602372
MinIO client pgsty/mc:RELEASE.2026-11-12T00-00-00Z@sha256:b532278b7a3747dbab6fe45eebb40a653efa704e6758e24e9d9ec54fc96c1800
RabbitMQ rabbitmq:3.13.7-alpine@sha256:d7af1c87c5f1eda13fcfca06db452bf3aeab6619fc3358b68535c0c02c4e52bc
HAProxy haproxy:3.2-bookworm@sha256:baecd003ae5c2376e58d04a5b2ffc7d82d30e9bebe2869f76222b819f719dee3

Официальные minio/minio и minio/mc с Docker Hub в этой среде недоступны (репозитории сняты, quay.io/minio отвечает 401). Взят тот же сервер MinIO из pgsty/minio. Его entrypoint не читает MINIO_ROOT_*_FILE, поэтому infra/minio-entry.sh экспортирует корневые учётные данные из Docker secrets и запускает server /data. Клиент pgsty/mc запускается с entrypoint на infra/minio-bootstrap.sh: бакет messenger-attachments остаётся приватным, приложению выдаётся отдельный пользователь и политика.

Секреты создаёт bootstrap и кладёт их в secrets/ (каталог в .gitignore). В репозиторий не входят .env и значения паролей.

powershell -File scripts/bootstrap.ps1
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --scale api=2

Дождаться GET http://127.0.0.1:8080/health/ready со статусом 200. Миграции 001–004 применяет одноразовый сервис migrate до старта API. Публичный порт только у HAProxy (8080). Порты API наружу не публикуются.

Проверки:

$env:PYTHONUTF8 = "1"
python scripts/check_contract.py
python tests/smoke.py --base-url http://127.0.0.1:8080
python student-tests/grade4.py
python student-tests/persistence_hook.py
python student-tests/failover.py

make test вызывает тот же smoke. На Windows хуки отказов — scripts/restart.cmd и scripts/stop-one.cmd; на POSIX — scripts/restart.sh и scripts/stop-one.sh.

Безопасная остановка без удаления данных: docker compose --env-file .env stop. Полное удаление учебных томов (сообщения, сессии, объекты, очередь) — отдельное намеренное действие: docker compose --env-file .env down -v. Эту команду нельзя использовать как перезапуск.

После failover остановленная реплика API остаётся остановленной (restart: unless-stopped). docker compose restart её не поднимает. Вернуть обе реплики: docker compose --env-file .env up -d --scale api=2.

Повтор уже обработанной failed-задачи делает оператор внутри worker-контейнера: python -m app.replay JOB_ID. Это не публичный HTTP-метод.

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

Из lab4 перенесены PostgreSQL как источник истины, сессии в Redis (AOF, Argon2id), две реплики API за HAProxy, приватный бакет, ключи идемпотентности сообщений, X-Request-Id и X-Instance-Id (hostname контейнера, короткий id). Загрузка больше не отвечает 201 и не делает resize в процессе API.

POST /api/v1/attachments отвечает 202 только после двух устойчивых шагов: байты лежат в staging/{attachment_id}, и в одной транзакции PostgreSQL записаны вложение со статусом queued, строка attachment_jobs и строка job_outbox. API в брокер не публикует и не зависит от него для ответа 202. /health/ready проверяет PostgreSQL, Redis и S3.

Отдельный процесс relay читает неопубликованные строки outbox и публикует durable-сообщение в exchange attachments с publisher confirm. Только после confirm ставится published_at. Сообщение соответствует contracts/jobs.schema.json: schema_version, type=attachment.process.v1, job_id, attachment_id, pipeline_version, attempt, created_at. Байтов и учётных данных в нём нет. Ключи S3 worker читает из базы.

Очередь attachment.jobs durable, prefetch равен WORKER_CONCURRENCY (2). Подтверждение consumer — ручное и только после эффекта: объекты att/{id}/original, thumbnail, crop, optimized записаны, варианты и статус ready зафиксированы одной транзакцией, staging удалён. Повторная доставка перезаписывает те же ключи. ready ставится, когда есть все три варианта. Более старый pipeline_version не затирает более новый. В этой работе версия всегда 1.

Варианты (src/app/pipeline.py): ориентация EXIF применяется через ImageOps.exif_transpose, альфа накладывается на белый фон, метаданные снимаются копированием в новое RGB-изображение. Thumbnail вписывается в 256×256 без увеличения (для fixture 320×200 получается 256×160). Crop — наибольший центральный квадрат, затем 128×128, увеличение разрешено. Optimized — WebP, вписывание в 1280×1280 без увеличения. JPEG quality 85 и optimize=True, WebP quality 80 и method 6. Рендер идёт в отдельном процессе с таймаутом JOB_TIMEOUT_SECONDS (45), чтобы зависание декодера не блокировало цикл worker.

Пределы: тело загрузки MAX_UPLOAD_BYTES = 10 МиБ, MAX_IMAGE_PIXELS = 40e6, оценка распакованного RGBA против WORKER_IMAGE_MEMORY_BYTES = 256 МиБ, память контейнера worker = 1024 МиБ. Постоянные ошибки (invalid_image, payload_too_large, пропавший staging, несовпадение checksum) сразу дают failed. Временные (сбой обработки, таймаут, S3 503) повторяются. Пауза: 0.4 * 2^(attempt-1) секунд, потолок 8 с, плюс равномерный jitter [0, 0.4], сумма тоже не выше 8 с. После 5 попыток статус failed, error_code=retry_exhausted, строка попадает в job_failures и копия — в attachment.jobs.dlq.

Lease JOB_LEASE_SECONDS = 90 и обязан быть больше таймаута обработки. Просроченный processing sweeper возвращает в queued и кладёт новую строку outbox. Если попытки кончились — failed. Явный replay готовой задачи с тремя вариантами возвращает already_ready и новой работы не создаёт. Replay failed сбрасывает попытку, ставит queued и новую строку outbox.

Staging GC не удаляет, пока задача queued/processing или failed моложе STAGING_RETENTION_SECONDS (86400). Осиротевшие объекты под att/ по-прежнему удаляются после grace.

Переменные .env.example (JOB_*, JPEG_QUALITY, WEBP_*, PIPELINE_VERSION, STAGING_RETENTION_SECONDS, WORKER_IMAGE_MEMORY_BYTES, BROKER_URL_FILE) читает src/app/config.py. SESSION_STORE в примере оставлен как подсказка lab2; сессии этой работы живут в Redis. APP_ROLE разделяет api, migrate, gc, worker, relay.

Вложения queued и processing можно прикрепить к сообщению. failed даёт 409. Скачивание содержимого до ready даёт 409. Ответ 202 — снимок queued с пустым списком вариантов, даже если worker успел закончить раньше отправки ответа.

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

Дата прогона: 2026-11-20. Хост: 12th Gen Intel Core i7-12700H, 31,6 ГиБ RAM, Docker Desktop 29.6.1. Лимиты контейнеров заданы в compose.yaml (API 0,5 CPU / 512 МиБ, worker 1 CPU / 1024 МиБ, PostgreSQL 1 CPU / 512 МиБ, RabbitMQ 0,5 CPU / 384 МиБ, Redis 0,5 CPU / 128 МиБ, MinIO 0,5 CPU / 256 МиБ).

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Контракт не ослаблен python scripts/check_contract.py при PYTHONUTF8=1 PASS вывод команды в сессии
Публичный smoke: 202, ready, JPEG thumbnail python tests/smoke.py --base-url http://127.0.0.1:8080 PASS: lab5 public API scenario... за ~14 с evidence/smoke.txt
Минимум lab4: 2 реплики, сессия, идемпотентность, приватный S3 тот же smoke и failover ниже два X-Instance-Id чередуются; бакет приватный, bootstrap создаёт отдельного пользователя evidence/failover.json
202 только после staging и записи задания; worker можно остановить python student-tests/grade4.py, сценарий worker stopped attachment 5886b435-004d-4aed-b8f7-9a288c7bc181, job c6d3c7ff-a181-41f9-a945-e194054b0637: content 409, после рестарта API и RabbitMQ статус ready evidence/grade4.json
Durable broker, at-least-once, ack после эффекта тот же прогон, crash after S3 before ack attachment a5a24455-f783-4511-90f9-0b17dd43aaf5, job 0fdaa8f2-054b-4aa0-a273-e63a425ce8c6: в логе crash до ack, после рестарта ready, по одной строке crop/optimized/thumbnail evidence/grade4.json
Состояния и три варианта happy path того же прогона attachment a813b0a0-2bab-404f-aa5f-8850b46db20c дошёл до ready; thumbnail/crop/optimized проверены кодом теста evidence/grade4.json
Ограниченный retry и безопасный error_code inject transient до исчерпания job d118acc1-f4cb-4a6e-8fd3-7f7f74d5cbd3, error_code=retry_exhausted, 5 строк в реестре failed evidence/grade4.json
Outbox: разрыв COMMIT и publish relay не публикует, затем процесс поднимается снова attachment 35000ce9-e4d5-4774-a7de-6b717a4cb208: до рестарта 1 неопубликованная строка, затем ready evidence/grade4.json
Crash relay после commit outbox до publish fault relay_exit_before_publish job 5104d370-c0d6-48f1-916a-6611afb8958f, gap_injected=true, лог выхода есть, итог ready evidence/grade4.json
Lease зависшего processing lease истёк, sweeper вернул задачу job 6ebf2c9f-090a-4637-94b2-2eb0a87f356b дошёл до ready evidence/grade4.json
Явный replay и запрет дубля ready python -m app.replay из student-tests/grade4.py первый replay enqueued, после ready второй replay already_ready evidence/grade4.json
Таймаут обработки не роняет API stall дольше JOB_TIMEOUT_SECONDS job ec75b92c-2534-4d96-adf5-4a92d252d389: API оставался ready, затем replay довёл вложение до ready evidence/grade4.json
Сохранность при рестарте томов python student-tests/persistence_hook.py PASS: persistence preserved confirmed data and existing session. Хук scripts/restart.cmd перезапускает postgres, redis, minio, rabbitmq, api, worker, relay, gc, lb и не удаляет тома вывод команды в сессии 2026-11-20
Остановка одной реплики API python student-tests/failover.py до отказа видны 2 instance id; 91 успешная запись, 1 сбой, первая успешная запись через 4,541 с; остановленная реплика перестала обслуживать. PASS: failover preserved confirmed data and existing session. evidence/failover.json

student-tests/grade4.py сам возвращает infra/faults.json к безопасному виду: все флаги выключены, stall_seconds и timeout_seconds равны 0. Так файл и лежит после прогона.

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

Гипотеза для уровня 4: принятая задача доживает до одного и того же ready, если оборвать публикацию, процесс после записи объектов или зависший lease, потому что эффект идемпотентен по ключам S3, а намерение живёт в PostgreSQL. Это проверено сценариями выше, а не отдельным треком нагрузки.

Короткий закрытый цикл отправки сообщений (не обработка изображений) нужен только как ориентир живого стенда. Прогрева отдельного не было, один прогон, клиентский overhead входит в задержку.

Команда: python tests/load.py --base-url http://127.0.0.1:8080 --duration 15 --concurrency 4 --output evidence/load.json

Результат: 15,604 с, 627 успешных POST, 0 ошибок, 40,183 успешных RPS, p50 80,3 мс, p95 198,0 мс, p99 302,7 мс. Один снимок docker stats в середине прогона (evidence/docker-stats.txt): API около 42% и 54% CPU при ~90 МиБ из 512 МиБ, HAProxy 17% CPU, PostgreSQL 14% CPU и 50 МиБ, Redis 8 МиБ. Worker и MinIO в этом профиле почти простаивали: сообщений с картинками цикл не шлёт. Снимок RabbitMQ (54% CPU, 186 МиБ из 384 МиБ) — одно мгновение, не профиль очереди картинок. Закрытый цикл занижает очередь ожидания и не доказывает предел throughput.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Worker остановлен, затем рестарт API и RabbitMQ с томами 202 сохраняет задачу, content до ready даёт 409, после старта worker то же вложение ready так для 5886b435-004d-4aed-b8f7-9a288c7bc181 данные принятой загрузки сохранены
Relay не публикует строку outbox после нового процесса relay та же задача доходит до ready 1 неопубликованная строка, затем ready ручное новое задание не создавалось
Процесс relay завершается после commit outbox и до publish следующий процесс публикует ту же строку gap_injected=true, ready задача не потеряна
Процесс worker завершается после записи S3 и до ack повторная доставка дописывает те же ключи и один набор вариантов crash в логе, по одной строке каждого варианта, ready дубля вариантов нет
Lease processing истёк sweeper возвращает задачу в очередь ready подтверждённый результат не откатился
5 временных ошибок failed и retry_exhausted, replay снова ставит задачу, повторный replay ready ничего не делает 5 строк реестра, enqueued, затем already_ready дубль успешной задачи не исполнялся
Рестарт postgres, redis, minio, rabbitmq, api, worker, relay, gc, lb сессия и подтверждённое сообщение живы PASS persistence тома не удалялись
docker stop одной реплики API вторая продолжает писать, остановленная не отвечает 2 instance id до отказа, восстановление записи за 4,541 с, 1 неуспешная попытка из цикла подтверждённые сообщения и вложение целы

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

Стенд — один Docker-host. Потеря этой машины уносит PostgreSQL, Redis, MinIO и RabbitMQ вместе. Две реплики API переживут остановку одной из них и не переживают остановку HAProxy или базы.

Доставка at-least-once. Идемпотентность держится на ключах объектов и условной записи ready, это не exactly-once. Повторная загрузка того же файла создаёт новое вложение: контракт не делает upload идемпотентным.

pipeline_version в конфигурации всегда 1. Защита от перезаписи новым результатом старой версии в коде есть, автоматический прогон нескольких версий pipeline — материал трека 5 и здесь не измерялся.

Replay — команда оператора в контейнере worker, не метод публичного API. Сравнение concurrency/prefetch и lag очереди на разных размерах изображений не проводилось: это трек 5.

/health/ready не ждёт брокер. Пока relay жив, отставание outbox подхватывается само; если relay остановлен надолго, API продолжает принимать 202, а обработка стоит до его старта. GC не слушает HTTP, поэтому healthcheck образа для него отключён в Compose: иначе контейнер помечался бы больным из-за проверки порта 8080.