14 KiB
Отчёт — лабораторная 5
- Автор, группа: Самохвалов Андрей Ремович, БПИ-2302.
- Целевая оценка: 5, трек 2 «Доказанная идемпотентность pipeline». Уровни 3 и 4 тоже проверены.
- Ветка:
solution/bpi2302-samohvalov. Локальныеdocs/plans/иLAB_NOTES.mdне входят в коммиты. - Источники:
README.md,COURSE.md,contracts/README.md,contracts/attachment-states.md,contracts/jobs.schema.json,contracts/openapi.json, публичные тесты и собственная lab4. Python 3.12.12, FastAPI 0.118.3, Pillow 11.3.0, psycopg 3.2.12, MinIO SDK 7.2.20, pika 1.4.4. Помощь ИИ: Codex; факты ниже проверены на синтетических данных.
Запуск из чистого clone
Нужны Docker Compose и Python 3.9+. Наружу опубликован только HAProxy на 127.0.0.1:${APP_PORT:-8080}; паролей в Git нет.
cp .env.example .env
python3 scripts/setup-local-secrets.py
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --scale api=2
docker compose --env-file .env up -d --wait --scale api=2 api lb worker publisher
make check
make test
Скрипт создаёт только отсутствующие секреты с правами 0600. migrate, s3-volume-init, s3-bootstrap, broker-init — одноразовые роли: Exited (0) для них штатен. Миграции применяются под PostgreSQL advisory lock. Остановить стенд без потери учебных данных: docker compose --env-file .env down. Только для намеренного удаления синтетических данных: docker compose --env-file .env down -v.
Образы: PostgreSQL 17.6, RabbitMQ 4.1.8-management, HAProxy 3.0.11, Python 3.12.12, MinIO RELEASE.2025-10-15T17-29-55Z и MinIO Client 2025.7.21-debian-12-r3 (S3-образы закреплены digest). Проверено в Colima/arm64: 2 CPU, 2 GiB RAM. На этом хосте Docker build не разрешал DNS files.pythonhosted.org; сборка применяла только локальный ignored compose.local.yaml с временным адресом CDN через COMPOSE_FILE=compose.yaml:compose.local.yaml. При обычном DNS/PyPI он не нужен.
Архитектура и границы надёжности
Клиент → HAProxy → две API-реплики. PostgreSQL — источник истины для пользователей, сообщений, вложений, jobs, outbox и версий. MinIO хранит байты в закрытом bucket. RabbitMQ переносит только ID и служебные поля jobs.schema.json, без изображения, credentials, клиентского пути или произвольного URL.
| Роль | Health, volume, пределы | Доступ |
|---|---|---|
lb |
проверка API backends, без данных | единственный host port |
api ×2 |
/health/ready, 0,5 CPU/256 MiB каждая |
DB URL и ограниченные S3 credentials |
postgres |
pg_isready, postgres_data |
локальный secret |
s3 |
/minio/health/ready, s3_data, 0,5 CPU/384 MiB |
root только внутри S3/bootstrap |
broker |
rabbitmq-diagnostics ping, broker_data |
AMQP URL через secret, без host port |
publisher |
отдельный процесс с publisher confirms | DB и AMQP, без S3 |
worker |
отдельный процесс, 0,5 CPU/768 MiB, prefetch=1 | DB, AMQP, объектные S3 права |
staging-cleanup |
периодический процесс | DB и отдельные S3 maintenance credentials |
API потоково принимает до 10 MiB PNG/JPEG, сверяет MIME с содержимым и ограничивает изображение 40 млн пикселей. Имя файла используется только для отображения. Перед S3 PUT создаётся временный upload marker; полный staging-object затем сверяется по размеру и SHA-256. Одна транзакция записывает attachment, job и outbox, и лишь после COMMIT API отвечает 202 queued. Поэтому остановленный broker/worker не теряет принятую загрузку; другие сообщения и ссылка на queued-вложение того же чата работают. Пока нет ready, скачивание отвечает 409.
Publisher арендует outbox, публикует persistent сообщение в durable quorum queue и отмечает outbox только после broker confirm. Потеря DB-подтверждения может создать вторую доставку. Worker захватывает job под lease, читает доверенные метаданные из PostgreSQL, сверяет исходные байты и пишет объекты с детерминированными ключами. Статус ready фиксируется лишь после всех четырёх внутренних эффектов: original, thumbnail, crop, optimized. Публичная metadata показывает три производных варианта; доступ к каждому проходит проверку членства в чате через API.
Original остаётся побайтно неизменным. Thumbnail — JPEG quality=85, optimize=True, вписан в 256×256 без увеличения и с округлением вниз: 320×200 → 256×160. Crop — центральный JPEG 128×128; маленький исходник может увеличиваться. Optimized — WebP quality=82, method=4, вписан в 1280×1280 без увеличения. EXIF orientation применяется к производным, alpha кладётся на белый фон, EXIF и прочие метаданные в производные не передаются. Уменьшение размера в байтах каждого файла не обещается.
Worker имеет 60-секундный deadline/lease, одно текущее сообщение и контейнерный предел памяти. Временная ошибка повторяется до 5 попыток с экспоненциальной базой 1–30 с и jitter до 50%; invalid_image постоянна, storage_unavailable и worker_timeout повторяются. Исчерпанная job остаётся failed с безопасным error_code в БД: это реестр вместо отдельной DLQ-очереди. Операторский replay требует явной команды и пишет audit, а ready job повторно не исполняется:
docker compose --env-file .env exec -T worker python -m src.replay JOB_UUID --operator local-operator --reason 'verified repair'
Вторую версию исследователь запускает через python -m src.reprocess ATTACHMENT_UUID в worker-контейнере. Команда принимает только ready с проверенным оригиналом. Версия 1 читает staging, следующие версии — неизменный конечный original. Уникальность (attachment_id, pipeline_version, name) и lease token защищают текущий результат от старой доставки. После COMMIT worker удаляет staging по возможности; staging-cleanup повторяет удаление после сбоя. Orphan без job удаляется только после 3600 с и перепроверки upload marker/БД; queued/processing источник сохраняется.
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдение | Evidence |
|---|---|---|---|
| Общий стенд и quorum | docker compose up -d --build --scale api=2; restart broker; rabbitmqctl list_queues |
Все роли поднялись; durable quorum queue сохранилась после restart | evidence/broker-restart.txt, compose.yaml |
| Публичный API | make test BASE_URL=http://127.0.0.1:8085 после финальной сборки |
PASS; original побайтно верен, thumbnail 256×160 | tests/smoke.py |
| Durable handoff | student-tests/test_upload_handoff.py: broker/worker down → 202/409 → restart API/broker |
PASS; сообщение с вложением создано, та же job стала ready | собственный тест |
| Окно publish→confirm | student-tests/test_publish_confirm_gap.py |
После первой broker confirm outbox остался pending; повтор дал 2 копии в очереди, но один логический ready-результат | evidence/pipeline-faults-2026-10-02.md |
| Варианты, доступ и лимиты | student-tests/test_image_pipeline.py в worker; test_variants_api.py через LB |
5/5 unit; все 3 варианта совпали с metadata/hash, original точен, чужой пользователь 404 | собственные тесты |
| Retry, lease, replay, версия, crash | student-tests/test_pipeline_faults.py на существующих и пустых томах |
В обеих сериях 6/6 PASS, включая смерть процесса до/после S3 и после result COMMIT | evidence/pipeline-faults-2026-10-02.md |
| Очистка staging | student-tests/test_staging_cleanup.py в maintenance-контейнере |
Старый orphan удалён, active upload сохранён, expired marker/object удалены | собственный тест U2 |
| Persistence/failover | make test-persistence ACTION_SCRIPT=scripts/restart.sh; make test-failover ACTION_SCRIPT=scripts/stop-one.sh |
PASS; сохранены токен/данные после остановки API/LB/publisher/worker/cleanup/broker/PG/S3; 133 успешные записи, 0 ошибок, восстановление 1,327 с | hooks, tests/resilience.py |
| Нагрузка | tests/load.py 30 с/4 клиента; scripts/measure-image-pipeline.py 20+20 файлов/4 клиента |
22 419 сообщений без ошибок, 747,002 RPS; 40/40 изображений ready за 14,150 с | evidence/load-2026-10-02.json, evidence/image-load-2026-10-02.json, evidence/image-resource-samples-2026-10-02.txt |
Эксперимент трека 5 и замеры
Гипотеза: подтверждённая job и её эффект останутся логически единичными при дублировании, перестановке версий и смерти worker до/после S3 и COMMIT. evidence/pipeline-faults-2026-10-02.md описывает две обезличенные серии: одна на существующих томах, другая в отдельном изначально пустом PostgreSQL/S3 проекте (до теста 0 jobs/replays). В каждой серии 6/6 PASS; у каждой готовой версии ровно четыре внутренние записи, current version и SHA-256 оригинала верны. Тест publish→confirm намеренно создал две копии в RabbitMQ. Это идемпотентность эффекта, не exactly-once доставка.
Текстовая closed-loop нагрузка 30,012 с, concurrency=4: 22 419 успешных POST, 0 ошибок, 747,002 успешных RPS, latency p50/p95/p99=4,109/11,019/36,533 мс. Closed-loop не измеряет предельную пропускную способность image pipeline и имеет coordinated omission/накладные расходы клиента.
Изображения: 20 PNG 320×200 по 111 817 байт и 20 PNG 800×600 с псевдослучайными пикселями по 1 441 103 байт; concurrency=4, 40/40 ready, 0 ошибок, 14,150 с (~2,827 ready/s). Для маленьких upload p50/p95/p99=20,276/29,796/30,022 мс, от начала upload до ready=1273,778/1285,587/1287,102 мс. Для больших upload=29,097/54,469/57,979 мс, до ready=1585,251/2256,920/2571,138 мс. os.urandom сохраняет размер/разрешение профиля, но не конкретный hash между запусками. Poll каждые 0,3 с увеличивает наблюдаемое время ready; p95/p99 основаны на 20 результатах каждого размера. Выборочные Docker stats во время серии: API 85–86 MiB на реплику, worker 49–61 MiB, S3 182–184 MiB; это снимки, не пик памяти.
После failover вторая API-реплика восстановлена командой docker compose up -d --wait --scale api=2 api lb. Основные тома сохраняют синтетические записи; отдельные пустые тома эксперимента удалены только в проекте mtusi2026lab5fresh.
Ограничения
Единственные PostgreSQL, MinIO, RabbitMQ и Docker-host остаются точками отказа; quorum queue на одном узле не означает кластерную доступность. При недоступности зависимости worker повторяет работу или достигает failed, а не выдаёт ложный ready. Serial worker/prefetch=1 и 60-секундный deadline подходят для учебных лимитов 10 MiB/40 млн пикселей; на другом оборудовании нужны новые замеры. Локальный HTTP используется только с синтетическими данными; удалённой демонстрации нужен TLS. Публичный smoke подтверждает обязательный минимум; отказные сценарии и трек 5 проверены отдельно.