Files
mtusi2026lab5/REPORT.md
T

27 KiB
Raw Blame History

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

  • Автор, группа: Кушнаренко Николай Вячеславович, БПИ2302
  • Целевая оценка; выбранный трек 5, если нужен: 5, трек 1 «Очередь под перегрузкой»
  • Commit/PR: ветка solution/bpi2302-kushnarenko в форке kolya; ссылка на PR добавляется после открытия
  • Использованные источники, библиотеки и помощь ИИ: Python 3.12, uvicorn, asyncpg, aiobotocore, aio-pika (RabbitMQ), Pillow (обработка изображений); RabbitMQ 4.1.8, SeaweedFS 4.48, PostgreSQL 17, Valkey 8, HAProxy 3.0. Код lab4 перенесён. ИИ-ассистенты использовались для помощи с кодом, тестами и отчётом; Codex проверил подготовку к сдаче, исправил перенос reconciler, усилил методику исследования и выполнил реальные запуски 12.11.2026

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

Prerequisites: Docker Compose v2, bash (Git Bash на Windows), Python ≥ 3.9; на Windows PYTHONUTF8=1. Версии: python:3.12.12-slim-bookworm@sha256:593bd06e…, postgres:17.11-alpine@sha256:b0f9560a…, valkey/valkey:8.1.10-alpine@sha256:081c2f5c…, haproxy:3.0-alpine@sha256:56b887da…, chrislusf/seaweedfs:4.48@sha256:4e61d15f…, rabbitmq:4.1-alpine@sha256:6a0f7984… (4.1.8), зависимости — requirements.txt (закреплены).

sh scripts/init-secrets.sh               # secrets/*: БД, S3 (admin + ключи API), RabbitMQ (rabbitmq.conf, broker_url)
cp .env.example .env
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait --wait-timeout 120   # postgres, valkey, seaweedfs, rabbitmq -> migrate + s3-init -> api x2, worker -> lb
curl http://127.0.0.1:8080/health/ready
python3 tests/smoke.py --base-url http://127.0.0.1:8080          # upload -> 202 -> ready -> thumbnail 256x160
python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080
python3 tests/resilience.py --mode failover    --action-script scripts/stop-one.sh --base-url http://127.0.0.1:8080
sh scripts/restore-replicas.sh
# собственные тесты
python3 -m unittest discover -s student-tests -p "test_api.py" -v      # + test_idempotency.py, test_attachments.py
python3 student-tests/test_pipeline.py                                  # Pillow желателен (пиксельные проверки)
python3 student-tests/test_resilience5.py                                # семь окон отказа
python3 student-tests/test_reconcile5.py                                 # варианты и staging не удаляются
python3 student-tests/test_expiry.py
python3 student-tests/test_dependencies.py
# операторские команды
docker compose --env-file .env run --rm -T worker python -m app.replay list
docker compose --env-file .env run --rm -T worker python -m app.replay replay <attachment_id>

Windows: scripts/restart.cmd, scripts/stop-one.cmd. Остановка с сохранением данных — docker compose --env-file .env stop; намеренное удаление учебных данных — down -v (volumes pgdata, valkeydata, seaweeddata, rabbitmqdata). Учётные данные RabbitMQ задаются конфигурационным файлом-секретом secrets/rabbitmq.conf; hostname контейнера фиксирован (rabbitmq), иначе очередь не переживает пересоздание контейнера.

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

Клиент ─▶ LB ─▶ API ─┬─(1) staging в S3 (приватный prefix staging/)
                     └─(2) ОДНА транзакция PostgreSQL: attachments(status=queued) + outbox  ──▶ 202 queued
outbox ──relay (в API и worker, SKIP LOCKED)──▶ RabbitMQ (quorum, persistent, publisher confirm) ──▶ worker
worker: claim(queued→processing, lease) → staging → thumbnail/crop/WebP → S3 att/<id>/… → ОДНА транзакция: варианты + ready → ack → очистка staging
Роль Сервис Health Volume Credentials
Брокер rabbitmq 4.1.8 rabbitmq-diagnostics ping rabbitmqdata secret rabbitmq.conf; клиентам — secret broker_url
Worker worker (отдельный процесс, тот же образ; 1 CPU / 768 MiB) heartbeat-файл (<30 с) — secrets БД/S3/брокер
остальные как в lab4
  • Границы приёма (до 202): байты проверены (формат, целостность, размеры) и записаны в устойчивый staging (приватный S3-prefix staging/<id>, не локальный диск); метаданные и намерение обработки записаны одной транзакцией PostgreSQL (таблицы attachments и outbox). Только после COMMIT клиент получает 202 со снимком status=queued. Если брокер недоступен — это не мешает приёму: задание остаётся в outbox и публикуется позже. HTTP-передача байт клиентом по-прежнему синхронна (честная граница: staging уже в S3).
  • Состояния и переходы (contracts/attachment-states.md): queued → processing → ready | failed; processing → queued при временной ошибке (backoff) и при истечении lease (sweeper); failed → queued только явным операторским replay. Повторная доставка готовой задачи — no-op с ack; завершённое состояние не откатывается дубликатом. Условия UPDATE (status='queued', lease_owner=…) исключают конкурирующую запись.
  • Задание в брокере (jobs.schema.json): только schema_version, job_id, type, attachment_id, pipeline_version, attempt, created_at — без байт, ключей S3 и credentials; worker берёт доверенные метаданные (ключи, тип) из БД. job_id не меняется при redelivery; attempt — управляемая попытка.
  • Доставка и подтверждения: durable quorum-очередь attachment.process, persistent-сообщения, publisher confirm (подтверждение приёма брокером) → только затем published_at в outbox; ack consumer — только после COMMIT результата (устойчивый эффект). Это разные границы. Доставка at-least-once; эффект идемпотентен: ключ (attachment_id, pipeline_version, name) (PK attachment_variants, ON CONFLICT DO NOTHING), детерминированные ключи объектов S3.
  • Обработка (src/app/pipeline.py): thumbnail — JPEG, вписан в 256×256 без увеличения, EXIF-ориентация применяется, alpha на белый, размеры округляются вниз (320×200 → 256×160), quality 85, метаданные не сохраняются; crop — JPEG, центрированный квадрат 128×128 (мелкие допускается увеличивать); optimized — WebP, вписан в 1280×1280 без увеличения, quality=80, method=4, EXIF/ICC не сохраняются, прозрачность сохраняется. size_bytes/sha256/content_type вложения всегда описывают оригинал; у вариантов — свои поля. Готовность (ready) ставится после сохранения оригинала и всех вариантов.
  • Лимиты обработки: API отклоняет файл >10 MiB (413) и >40 млн пикселей (413) до распаковки; worker — таймаут задания 45 с (JOB_TIMEOUT), число пикселей, WORKER_CONCURRENCY (= prefetch = число потоков), лимит памяти контейнера 768 MiB; JPEG >2560×2560 декодируется сразу в масштабе 1/2.
  • Retry: ограниченное число попыток MAX_ATTEMPTS=5; временные ошибки (S3/БД/таймаут) → queued + новая запись outbox с отложенной публикацией; задержка — экспоненциальный backoff с jitter (случайное значение в [50 %, 100 %] от min(60 с, 2 с × 2^(n−1))); постоянные ошибки (нечитаемое изображение) → сразу failed с error_code (invalid_image, image_too_large, processing_failed); исчерпание попыток → failed/retry_exhausted.
  • Реестр failed и DLQ: реестр — таблица attachments со status=failed + job_events (журнал событий, без секретов); python -m app.replay list. Нечитаемые сообщения брокера (schema_version, типы) отправляются в DLQ attachment.process.dead через DLX. Replay (python -m app.replay replay <id>) допускается только для failed (иначе skipped): новая попытка, новый job_id, запись operator_replay в job_events; повторное исполнение уже успешной работы невозможно.
  • Lease и зависшие задачи: при захвате задание получает lease (LEASE_SECONDS=60); sweeper worker возвращает просроченные processing в queued (или failed/retry_exhausted); публиковать результат может только владелец lease (FOR UPDATE + проверка владельца).
  • Outbox (уровень 4): relay в API и worker читает FOR UPDATE SKIP LOCKED; после краха между COMMIT и publish задание публикуется автоматически (проверено). Повторная публикация после краха между confirm и published_at даёт дубликат, обрабатываемый как no-op.
  • Очистка staging: удаляется после COMMIT результата; для failed хранится STAGING_FAILED_RETENTION_SECONDS (7 суток) для разбора/replay; фоновая очистка не затрагивает текущую работу.
  • Backpressure: перед приёмом тела API проверяет число активных заданий; при queued+processing ≥ MAX_QUEUED_JOBS — 503 unavailable + Retry-After (контракт допускает 503). Readiness API не зависит от брокера и worker (их отказ не должен останавливать приём/чтение).

Исправления при подготовке к сдаче — 12.11.2026

Перенесено исправление HAProxy из ЛР4: когда общая БД недоступна и все API теряют readiness, резервный backend по liveness позволяет приложению вернуть контрактный JSON, Retry-After и X-Request-Id; /health/live остаётся доступен. Автоматический retry HAProxy ограничен ошибкой установления соединения, чтобы повтор уже отправленного upload POST не создавал лишнюю загрузку. Восстановлены собственные проверки TTL, PostgreSQL и Valkey.

Исправлен опасный перенос reconciler из ЛР4. Старый dry-run считал три готовых варианта осиротевшими, поскольку учитывал только attachments.s3_key; вывод до исправления сохранён в reconcile_before_fix.json. Теперь учитываются метаданные вариантов, staging и владелец серверного префикса att//… . Объект внутри префикса существующего вложения защищён даже до COMMIT метаданных worker. Перед удалением перепроверяются references и владелец. Такой подход консервативен: неизвестный объект внутри существующего вложения остаётся до отдельного операторского разбора.

Для staging можно явно выполнить docker compose run --rm -T api python -m app.reconcile --prefix staging/ (dry-run). Рабочий grace по умолчанию 900 с; --apply включает исправление. В тестах grace=0 применяется только к созданным тестом префиксам после окончания записи. Staging принятой задачи не удаляется; корректные оригинал и варианты не становятся failed. Очистку staging после ready и по retention для failed по-прежнему выполняет worker.

Повторный dry-run того же вложения после исправления: reconcile_after_fix.json — четыре объекта, orphan/missing/size mismatch = 0, изменений нет.

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

Текущий skeleton — 276dbda. README, COURSE, CONTRIBUTING, публичные tests/ и contracts/ сохранены без изменений. В Windows запущены Python-команды, соответствующие make check, make validate и make test. Полный реальный вывод — checks_2026-11-12.txt; команды всех собственных тестов — student-tests/README.md.

Проверка Результат
check_contract, полная OpenAPI-валидация, публичный smoke PASS; upload → 202 queued → ready; original и JPEG thumbnail проверены
API и аутентификация 12 тестов OK
Идемпотентность и несколько API-реплик 9 тестов OK
Изображения, лимиты, MIME, filename, ACL, private bucket, прерывание upload 11 тестов OK
Топология, порты, лимиты, непривилегированный пользователь 6 тестов OK
Варианты, EXIF, alpha, размеры, оригинал, redelivery, cleanup 9 тестов OK, включая пиксельные проверки Pillow
Безопасная сверка вариантов и staging 2 теста OK; сохраняются все варианты и незавершённый S3-эффект, orphan защищён grace и удаляется после него
Семь сценариев отказа pipeline 7 тестов OK: worker/API/broker, outbox, crash до COMMIT/ack, lease, retry exhaustion, registry/replay
TTL сессий и отказ PostgreSQL/Valkey 2 + 2 теста OK
Persistence и failover PASS; 121 успешных записей, 0 неуспешных попыток; восстановление 2.344 с
Bootstrap S3 дважды OK: bucket сохранён, анонимный доступ 403, создание bucket ключом API запрещено

Итого 60 собственных тестов. После экспериментов первый дополнительный persistence выявил гонку старта SeaweedFS: S3-порт уже открыт, но тома ещё не зарегистрированы, и чтение объекта получает 503. Этот неуспешный запуск сохранён в commands.txt. Исправлены операторские scripts/restart.sh и .cmd: после healthy модуль app.s3_recovery ждёт LIST и ranged GET существующих объектов, читая по одному байту с параллелизмом 8 и общим таймаутом 45 с. Это отдельная проверка восстановления, а не изменение публичного теста или обещание полной готовности S3 по /health/ready API. Для большого хранилища время такого обхода может превысить лимит; hook завершится ошибкой.

После исправления три последовательных persistence и финальный smoke прошли: restart_recheck.txt. lifecycle.json подтверждает в каждом повторе изменение StartedAt всех семи ролей (восемь контейнеров, включая две API-реплики), сохранение имён volumes и healthy после restart. SHA-256 изменённых после матрицы скриптов восстановления — restart_source_metadata.json; обработка API/worker и измерительные скрипты матрицы не менялись.

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

Гипотеза. Увеличение concurrency/prefetch ускоряет работу до насыщения CPU, но повышает память и может ухудшить latency крупных файлов. Ограничение приёма по глубине активной работы даёт предсказуемую перегрузку: отклонённые запросы получают Retry-After, а принятые задачи завершаются; после разгрузки приём восстанавливается.

Методика. Один worker, фактические лимиты проверяются через docker inspect: 1 CPU / 768 MiB, concurrency=prefetch ∈ {1, 2, 4}. Девять точек: small 320×200 PNG (109 KiB, 80 загрузок), medium 2400×1600 PNG (1961 KiB, 24 загрузки), large 6000×4000 JPEG (3100 KiB, 12 загрузок). Перед каждой точкой worker пересоздаётся, чтобы VmHWM начинался заново. Клиент — один Python-процесс, 8 одновременных загрузчиков; HTTP-соединения не переиспользуются после блокирующих Docker-команд. Неопределённый результат upload при сетевой ошибке автоматически не повторяется.

Клиент: Python 3.11.9, aiohttp 3.14.3, Pillow 12.3.0, matplotlib 3.11.2. Стенд: Docker Desktop, Linux-контейнеры; версии приложения и инфраструктуры закреплены в Git. На компьютере оставался другой Docker-проект. Время до ready = ready_at − accepted_at из PostgreSQL; p95 — nearest rank. Throughput — число ready / интервал от первого accepted_at до последнего ready_at: это измерение конвейера, включающее темп приёма следующих файлов. Queue lag — возраст старейшего активного задания (queued + processing); это не только ожидание в брокере. Глубина и возраст снимаются примерно каждые 0,4 с плюс время SQL/CLI. Пик RSS — VmHWM процесса worker, не память всего стенда.

concurrency Изображение ready Throughput, файлов/с p95, с RSS, MiB Пик queued+processing Возраст старейшего, с
1 small 80 23.84 2.84 72.5 67 2.7
1 medium 24 4.09 5.21 133.2 22 5.4
1 large 12 3.38 3.35 160.4 11 3.3
2 small 80 44.13 1.48 75.4 56 1.1
2 medium 24 4.6 4.78 194.9 22 4.3
2 large 12 3.84 2.98 250.9 12 2.7
4 small 80 52.3 1.25 79.9 50 1.1
4 medium 24 4.56 4.82 318.9 24 4.8
4 large 12 3.39 3.36 430.0 12 2.8

Все 348 из 348 загрузок матрицы достигли ready; failed=0, OOMKilled=false. Максимальный измеренный RSS — 430.0 MiB из 768. Наибольший throughput крупных изображений в этом прогоне получен при concurrency=2 (3.84 файлов/с, p95=2.98 с). Это наблюдение одного прогона на точку, а не статистически доказанный оптимум; близкие результаты следует считать сопоставимыми. На мелких файлах throughput изменился с 23.84 до 52.3 файлов/с при concurrency 1 → 4. Память крупных изображений: 160.4 → 430.0 MiB.

Backpressure и восстановление

MAX_QUEUED_JOBS=30, один worker concurrency=1, burst из 200 мелких файлов с 32 клиентами. Принято 54, получено 146 ответов 503; Retry-After реально прочитан и проверен (5 с). Пик активной очереди — 48, время разгрузки от начала burst — 2.7 с; все 54 принятых задач стали ready, failed=0, p95=1.88 с. После разгрузки три новые загрузки приняты и также достигли ready.

Порог является мягким, а не строгим резервированием мест: несколько запросов могут одновременно проверить старую глубину очереди перед приёмом тела. Поэтому пик может превышать 30. Число находящихся в приёме запросов дополнительно ограничено API concurrency/очередью и MAX_INFLIGHT. Для строгого лимита нужна атомарная резервация слотов. Этот эксперимент подтверждает ограничение приёма и восстановление, но не доказывает универсальную границу памяти при любом размере/параллелизме.

Из исследовательского скрипта удалён заранее выставленный retry_after_header_seen=True: результат определяется HTTP-заголовками. Проверяются коды/число ответов, отсутствие транспортных ошибок, готовность всех подтверждённых задач, восстановление, фактические ресурсы и OOM. Ошибка Docker или измерения не маскируется; промежуточные результаты сохраняются после каждой точки. Настройки API/worker восстанавливаются в finally.

Воспроизведение: python -m pip install -r research/requirements.txt, затем python research/queue_overload.py --out evidence/recheck_2026-11-12. Данные: queue_overload.json, вывод команд, SHA-256 исходников.

Матрица concurrency и размеров

Перегрузка и разгрузка очереди

Ограничения. Один компьютер, по одному прогону на точку, фиксированный worker CPU=1; фоновые процессы и темп клиента влияют на абсолютные числа. При нескольких worker или другом CPU результаты требуют повторной проверки. Октябрьские данные в evidence/queue_overload.json и старые PNG сохранены как исторические; текущие выводы основаны на повторе 12.11.2026.

Окна отказа (contracts/attachment-states.md)

Окно Воздействие Результат
после staging до записи задания сбой БД после записи в staging (lab4-механизм) staging удаляется компенсацией; иначе исправленный reconcile с --prefix staging/ и grace
после COMMIT до publish остановка брокера + kill всех API outbox довёл задание
после publish до confirm таймаут/разрыв публикация повторяется, дубликат — no-op
после записи S3 до COMMIT результата crash_once:after_s3_before_commit lease → повтор тем же результатом
после COMMIT результата до ack crash_once:after_commit_before_ack redelivery = no-op + ack

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

  • Один узел RabbitMQ, S3, PostgreSQL (SPOF). Отложенные повторы реализованы через outbox (брокерных delayed-exchange нет).
  • Один worker-процесс по умолчанию (WORKER_REPLICAS можно увеличить); lease и SKIP LOCKED/условные UPDATE допускают несколько worker.
  • Конкурентные записи старой и новой pipeline_version защищены ключом эффекта и условием pipeline_version <= job.pipeline_version; версионирование нескольких пайплайнов (трек 2) не реализовано.
  • Подтверждено экспериментами: различия измеренных throughput/p95/RSS, backpressure и восстановление; гипотеза без доказательства: поведение при >1 worker и при другом лимите CPU.