21 KiB
Отчёт — лабораторная 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.