Files
mtusi2026lab5/REPORT.md
T
2026-11-12 15:21:01 +01:00

30 KiB
Raw Blame History

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

  • Автор, группа: Санжаровский, БВТ2304
  • Целевая оценка: 4 (трек 5 не заявлен)
  • Commit/PR: ветка solution/bvt2304-sanzharovskiy форка Anatoly01/mtusi2026lab5, PR в mtusi2026/mtusi2026lab5
  • Источники и библиотеки: всё из lab4 (FastAPI, uvicorn, psycopg 3 + psycopg-pool, argon2-cffi, redis-py 8.1, boto3 1.38, Pillow 11.2, HAProxy 3.0, MinIO от Pigsty). Брокер — Redis Streams (тот же образ redis:7.4.1-alpine, отдельный экземпляр с AOF). Документация: Redis Streams (consumer groups, PEL, XAUTOCLAIM), Redis persistence (AOF, appendfsync always), RabbitMQ reliability/confirms (для сравнения границ confirm/ack), Pillow (draft, ImageOps.exif_transpose, WebP), Python resource (RLIMIT_AS/RLIMIT_CPU), multiprocessing forkserver; Transactional outbox (microservices.io). Использование ИИ: ИИ-ассистент помогал с кодом, тестами и текстом отчёта; решения разобраны и проверены прогоном.

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

Нужно: Docker Desktop (Compose v2), Python 3.9+ для тестов (только stdlib). Образы закреплены: python:3.12.7-slim-bookworm, postgres:16.4-alpine, redis:7.4.1-alpine (кэш сессий и брокер), haproxy:3.0.5-alpine, pgsty/minio:RELEASE.2026-08-04T00-00-00Z, pgsty/mc:RELEASE.2026-09-16T00-00-00Z. Новых образов по сравнению с lab4 нет.

cp .env.example .env            # Windows: copy .env.example .env — задать свои пароли/ключи
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
#   порядок: postgres(healthy) → migrate (exit 0, миграции 0001–0004)
#            s3(healthy) → s3-init (bootstrap, exit 0); broker(healthy)
#            → api ×2 → worker → lb
curl -i http://localhost:8080/health/ready          # 200 + X-Instance-Id
make check && make test                             # публичные проверки (Windows: set PYTHONUTF8=1)
python student-tests/collect_evidence.py            # ВСЕ проверки → evidence/*.txt (+ сводка)

Демонстрация уровня 3 вручную: scripts/stop-worker.(sh|cmd) → upload (202 queued, content 409) → docker compose restart api broker → scripts/start-worker.(sh|cmd) → ready. Всё это автоматически делает python student-tests/jobs.py --scenario worker-down.

Отдельные проверки:

python student-tests/jobs.py --base-url http://localhost:8080                 # все 8 сценариев отказов lab5
python student-tests/jobs.py --scenario crash-s3                              # один сценарий
docker compose --env-file .env exec -T api python -m app.tools limits-selftest  # лимиты worker
docker compose --env-file .env exec -T api python -m app.tools queue          # stream, pending, DLQ, outbox
docker compose --env-file .env exec -T api python -m app.tools job <attachment_id>
docker compose --env-file .env exec -T api python -m app.replay --list        # реестр failed
docker compose --env-file .env exec -T api python -m app.replay --attachment <id>   # явный replay
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover    ACTION_SCRIPT=scripts/stop-one.sh && scripts/restore-api.sh

Остановка без потери данных: docker compose --env-file .env down. Намеренное удаление учебных данных (БД, bucket и очередь): docker compose --env-file .env down -v. Имя проекта mtusi-lab5: volumes lab4 не затрагиваются.

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

клиент ─▶ lb (HAProxy, 127.0.0.1:8080) ─▶ api ×2 ──① PUT staging/<id> ──────────────▶ s3 (MinIO, private)
                                          │      ② BEGIN; attachments(queued) +           ▲  staging/<id>
                                          │         attachment_jobs + job_outbox; COMMIT   │  originals/<id>
                                          │      ③ XADD → broker  (ответ = «confirm»)     │  variants/<id>/v1/*
                                          │      ④ 202 queued                              │
                                          ▼                                                │
                                      postgres ◀──────── ⑦ COMMIT ready ──── worker ───────┘ ⑥ copy + PUT
                                   (истина: вложения,      ⑤ XREADGROUP ◀── broker (Redis Streams, AOF always,
                                    jobs, outbox,                                    volume brokerdata)
                                    variants, events)      ⑧ XACK ─▶ broker ;  ⑨ DELETE staging/<id>
Роль Service Версия Health/readiness Volume Порт
load_balancer lb haproxy:3.0.5-alpine /healthz; backend /health/ready — 127.0.0.1:8080 (+8081 ttl, +8082 fault — тестовые профили)
api ×2 api Dockerfile /health/ready (PostgreSQL) нет expose 8080
worker worker тот же образ, python -m app.worker heartbeat-файл обновляется раз в 1 c нет нет
broker broker redis:7.4.1-alpine + --appendonly yes --appendfsync always --maxmemory-policy noeviction redis-cli ping brokerdata нет
postgres, redis, s3, s3-init, migrate как в lab4 pgdata, s3data нет
тестовые api-fault, worker-fault (профиль fault), api-ttl (профиль ttl) тот же образ нет только через lb

Что перенесено из lab4 без изменений: LB + 2 реплики API без состояния, сессии (PostgreSQL + Redis-кэш), идемпотентность сообщений, проверка изображения по содержимому в API (413/415 синхронно, как в lab4), приватный bucket и отдельный пользователь MinIO, журнал upload_intents + janitor, лимиты, хуки. Переход по контракту: upload 201 ready → 202 queued.

Что добавлено в lab5:

  • Брокер — Redis Streams на отдельном экземпляре Redis с persistence. Обычный Pub/Sub не хранит сообщения; Stream хранит, а consumer group даёт at-least-once: выданное worker сообщение лежит в PEL (pending entries list), пока не будет XACK. appendfsync always — ответ на XADD отправляется только после fsync журнала AOF, это наш аналог publisher confirm. noeviction — сообщения никогда не вытесняются. Кэш сессий — другой экземпляр Redis без persistence (lab2).
  • Сообщение (app/broker.py, строго по contracts/jobs.schema.json): schema_version, job_id, type=attachment.process.v1, attachment_id, pipeline_version=1, attempt, created_at. Ни байтов, ни URL, ни ключей bucket, ни credentials. Worker берёт ключи объектов и sha256 только из БД. Сообщение, не прошедшее схему или с неизвестным job, уходит в DLQ-stream attachments:jobs:dlq.
  • Модель (migrations/0004_jobs.sql, только добавления — lab4 с новой схемой работает): attachments.staging_key; attachment_jobs (job_id, attempt, max_attempts, lease_token/lease_owner/lease_until, error_code, replays, UNIQUE(attachment_id, pipeline_version)); job_outbox (payload, available_at, published_at); attachment_variants с ключом эффекта PRIMARY KEY (attachment_id, pipeline_version, variant); job_events — журнал (реестр для оператора и audit replay).
  • Варианты (app/imaging.py): thumbnail — JPEG q85, вписан в 256×256, без увеличения, округление вниз, минимум 1 px (320×200 → 256×160); crop — JPEG q85, центрированный квадрат 128×128 (маленькие увеличиваются); optimized — WebP q80, method=4, вписан в 1280×1280 без увеличения, альфа сохраняется. EXIF orientation применяется до расчёта размеров; EXIF/XMP/ICC в результат не пишутся (проверено: у всех трёх вариантов exif=False, icc=False). Прозрачность в JPEG компонуется на белый. JPEG декодируется сразу в уменьшенном масштабе (draft), не меньше нужного самому большому варианту.
  • Ключи S3 детерминированы: originals/<id> (серверный CopyObject из staging/<id>), variants/<id>/v1/<variant>.<ext>. Повтор job перезаписывает те же объекты теми же байтами; в БД — ON CONFLICT DO NOTHING. Второго набора вариантов не бывает.
  • Лимиты worker (app/worker.py → дочерний процесс forkserver): байты — не больше MAX_UPLOAD_BYTES при скачивании из staging; пиксели — по заголовку до распаковки (MAX_IMAGE_PIXELS); память — RLIMIT_AS = IMAGE_MEMORY_MB (768 МиБ) у ребёнка, нехватка памяти даёт MemoryError в ребёнке, а не OOM всего worker; время — JOB_TIMEOUT_SECONDS (60 c) wall-clock, по истечении ребёнок убивается, плюс RLIMIT_CPU. Конкуренция — WORKER_CONCURRENCY=2 потока, каждый берёт по одному сообщению (COUNT 1, аналог prefetch=1). Контейнер worker: 1 CPU / 1 ГиБ.

Состояния и транзакционные границы

Переход Где Что устойчиво сохранено
нет → queued API: журнал → PUT staging/<id> → одна транзакция: снять журнал, attachments(queued), attachment_jobs(queued, attempt 1), job_outbox → COMMIT → XADD → 202 полный проверенный оригинал в staging, метаданные, job и сообщение в outbox
queued → processing worker, SELECT … FOR UPDATE: новый lease_token, lease_until = now()+20 c попытка, аренда, владелец
processing → queued временная ошибка, попытки есть: attempt+1, строка outbox с available_at = now()+backoff причина (last_error), время следующей попытки
processing → ready worker: S3 (copy + 3 PUT) → одна транзакция: варианты, attachment и job → ready (только если lease_token всё ещё наш) → XACK → удалить staging оригинал, три варианта, их sha256/размеры
processing → failed постоянная ошибка или attempt = max_attempts error_code (invalid_image, processing_failed, retry_exhausted), событие, копия в DLQ-stream
processing → queued (lease) reaper: аренда истекла ещё на одну аренду назад новая попытка через outbox
failed → queued python -m app.replay (только failed, только если staging ещё есть) событие replay (кто, когда), тот же job_id, attempt+1, бюджет ещё 5 попыток

Ready никогда не откатывается: повторная доставка ready-задачи — no-op с ack.

Окна отказа

Окно Что происходит Кто восстанавливает Проверка
после staging, до записи job объект в staging + строка upload_intents API компенсирует сразу; иначе janitor после grace (как lab4) orphans.py
после COMMIT, до publish job и outbox в БД, сообщения в брокере нет outbox relay (поток maintenance worker, раз в 1 c, строки старше 2 c, FOR UPDATE SKIP LOCKED) jobs.py outbox
брокер недоступен при upload XADD не прошёл за 2 c — 202 всё равно отдаётся relay, когда брокер вернётся jobs.py broker-down
после publish, до confirm брокер мог принять сообщение, а API не узнал relay опубликует ещё раз → дубль → no-op jobs.py redelivery
после записи S3, до COMMIT результата job в processing с арендой умершего worker, сообщение в PEL перезапущенный worker перечитывает свой PEL; после истечения аренды — takeover той же попытки; объекты S3 те же jobs.py crash-s3
после COMMIT результата, до ack job ready, сообщение в PEL redelivery → already_ready → ack jobs.py crash-ack
worker завис (аренда не продлевается) processing, lease истекает reaper → attempt+1 → другой worker; проснувшийся не может зафиксировать (fencing по lease_token) jobs.py lease

Retry, DLQ, replay

  • Постоянные ошибки (без повторов): изображение не декодируется / превышает пиксели / не хватило памяти → invalid_image; sha256 staging не совпал с БД или исходника нет → processing_failed.
  • Временные: S3 или БД недоступны, таймаут обработки, падение ребёнка. Повтор через outbox с экспоненциальным backoff и jitter («equal jitter»: d = min(60, base·2^(n−1)), задержка ∈ [d/2, d]). JOB_MAX_ATTEMPTS=5, затем failed retry_exhausted. Бесконечного немого retry нет.
  • Реестр failed — таблица attachment_jobs (status=failed, error_code, last_error) + job_events; копия для оператора — DLQ-stream. python -m app.replay --list / --dlq.
  • Replay (app/replay.py) безопасен: меняет только failed (FOR UPDATE), ready/queued/processing отклоняет — успешную задачу второй раз не исполнить. job_id тот же, attempt растёт, событие с actor. Если исходник уже удалён retention — отказ.

Аренда: долгая или зависшая задача

Живой worker продлевает аренду каждые lease/3 ≈ 6,7 c (отдельный поток heartbeat), пока ребёнок обрабатывает картинку. Поэтому долгая задача (в тесте 30 c при аренде 20 c) не перехватывается: аренда всё время свежая. Жёсткий предел — JOB_TIMEOUT_SECONDS. У мёртвого или замёрзшего worker аренда истекает. Тогда:

  1. сообщение из его PEL заберёт он сам после рестарта или другой worker (XAUTOCLAIM, 90 c); обработку получит тот, кто первым увидит истёкшую аренду;
  2. если за ещё одну аренду никто не перехватил, reaper переводит job в queued с новой попыткой.

Два неконтролируемых дубля невозможны: захват — SELECT … FOR UPDATE, фиксация результата сверяет lease_token. Старый worker после пробуждения получает LeaseLost и ничего не пишет в БД, а его объекты S3 совпадают байт в байт.

Очистка staging

  • ready: worker удаляет staging/<id> после COMMIT ready и ack; если не успел, подчищает maintenance через 30 c;
  • failed: исходник хранится STAGING_RETENTION_SECONDS (24 ч) для replay, потом удаляется;
  • брошенные загрузки (нет job): janitor по upload_intents, обход bucket проверяет и originals/, и staging/.

Текущую работу cleanup не трогает: удаляются только staging у ready и у failed старше retention.

Соответствие .env.example: WORKER_CONCURRENCY, JOB_MAX_ATTEMPTS, JOB_TIMEOUT_SECONDS, STAGING_RETENTION_SECONDS, MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS используются как есть; добавлены WORKER_REPLICAS, JOB_LEASE_SECONDS, JOB_BACKOFF_BASE/MAX_SECONDS, CLAIM_IDLE_SECONDS, IMAGE_MEMORY_MB. BROKER_URL задаёт compose (redis://broker:6379/0), поддерживается и BROKER_URL_FILE. SESSION_STORE — сессии всегда в PostgreSQL.

Readiness: /health/ready проверяет только PostgreSQL. Брокер не критичен для приёма — намерение лежит в outbox (проверено: брокер выключен → /health/ready 200, upload 202). S3 критичен только для вложений (как в lab4).

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

Основной прогон — Docker на ПК (Windows, Docker Desktop, стек из compose.yaml как есть): python student-tests/collect_evidence.py, все шаги PASS, выводы в evidence/<шаг>.txt. До этого код отлажен на локальном стенде без Docker (PostgreSQL 16, два процесса API за HAProxy, Redis-брокер с AOF, worker, S3-эмулятор moto) — evidence/local/*.txt, там те же результаты.

Критерий README Команда/сценарий Наблюдаемый результат (Docker) Файл
Публичный smoke make test PASS: lab5 public API scenario: 202 → ready, thumbnail 256×160 JPEG, sha256 evidence/smoke.txt
Брокер с persistence redis-cli CONFIG GET appendonly yes, appendfsync always, maxmemory-policy noeviction evidence/broker-config.txt
3: 202 только после устойчивого приёма; брокер и worker отдельно; API не делает resize jobs.py worker-down worker остановлен: 202 queued за 0,06 c; через 3 c всё ещё queued; content и thumbnail → 409; сообщение с queued-вложением → 201; задание лежит в stream (len=1) evidence/jobs-worker-down.txt
3: рестарт API и брокера с volumes → worker → ready jobs.py worker-down после restart broker + restart api сообщение на месте (len=1), тот же токен; worker запущен → ready за 2,5 c, оригинал побайтно, thumbnail 256×160, staging удалён evidence/jobs-worker-down.txt
3: at-least-once, ack после эффекта, повтор не создаёт второй набор jobs.py redelivery, crash-ack 2 дубля ready-задачи → no-op: 3 строки вариантов, 3 объекта S3, ready записан один раз, pending 0; crash после COMMIT → redelivery → no-op evidence/jobs-redelivery.txt, jobs-crash-ack.txt
3: ограниченный retry, финальный failed jobs.py retry-replay 5 попыток → failed retry_exhausted за 22 c; content → 409; прикрепить к сообщению → 409 evidence/jobs-retry-replay.txt
4: crop 128×128 и WebP smoke, jobs.py у каждого ready-вложения варианты thumbnail, crop, optimized evidence/jobs-*.txt
4: лимиты байт/пикселей/времени/памяти worker app.tools limits-selftest 5/5: 36 Мп при лимите 10 Мп → invalid_image: pixel limit; RLIMIT_AS 120 МиБ → memory limit; битый PNG → invalid_image; зависание 10 c убито через 2 c evidence/worker-limits.txt
4: outbox: crash между COMMIT и publish jobs.py outbox (api-fault) клиент получил 502; вложение и job закоммичены; relay опубликовал строку outbox → ready без нового upload evidence/jobs-outbox.txt
4: брокер недоступен при приёме jobs.py broker-down /health/ready 200; upload 202 за 2,1 c (таймаут publish 2 c); строка outbox не опубликована → брокер вернулся → relay → ready evidence/jobs-broker-down.txt
4: backoff с jitter, постоянные/временные, DLQ/реестр, безопасный replay jobs.py retry-replay, app.replay задержки 0,7 / 1,1 / 3,6 / 6,3 c (база 1 c: d = 1, 2, 4, 8, каждая в [d/2, d]); задача в replay --list, копия в DLQ с причиной retry_exhausted (injected_transient); replay → ready, тот же job_id, attempt 6, replays 1; повторный replay ready-задачи → refused evidence/jobs-retry-replay.txt, jobs-registry.txt
4: worker остановлен после записи объекта, до ack jobs.py crash-s3 os._exit(1) после записи S3; контейнер перезапустился, lease_takeover той же попытки (attempt 1) → ready за 26,9 c; по-прежнему ровно 3 варианта evidence/jobs-crash-s3.txt
4: lease/timeout зависшего processing jobs.py lease долгая задача 32 c при аренде 20 c — без перехвата (heartbeat); замёрзший worker → reaper → attempt 2 → ready за 37,3 c; проснувшийся старый worker не смог зафиксировать (fencing), результат не изменился evidence/jobs-lease.txt
4: ограниченная конкуренция, очередь под нагрузкой, очистка staging upload-memory + queue-drain; worker-down 90 загрузок по 9,6 МиБ → 90 × 202; worker (2 потока, 1 CPU) разобрал очередь за 103 c после окончания загрузок; staging удаляется после ready evidence/upload-memory.txt, queue-drain.txt
Возможности lab2–4 run.py, idempotency.py, attachments.py, orphans.py, s3_outage.py, upload_memory.py, persistence, failover ×2 30/30, 16/16, 91/91, orphans PASS, S3 outage 12/12, память процессов API +25–29 МиБ при 10–20 параллельных загрузках по 9,6 МиБ; persistence PASS; failover PASS дважды (0 неудачных попыток, восстановление 1,5 и 2,0 c) evidence/*.txt

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

Воздействие Что ожидаем Что наблюдали (Docker) Время восстановления / потеря данных
worker остановлен, upload 202 queued, обработки нет 202 за 0,06 c, 3 c queued работа ждёт в stream; 0 потерь
рестарт брокера (AOF) с необработанным заданием сообщение сохранено len=1 до и после ready через 2,5 c после старта worker
брокер остановлен при upload 202 без брокера 202 за 2,1 c, outbox не опубликован relay опубликовал после старта брокера, сценарий 14 c
api убит между COMMIT и publish задача не теряется 502 клиенту, job в БД ready без нового upload (сценарий 20 c)
worker убит после S3, до COMMIT та же попытка доходит до ready lease_takeover, attempt 1 26,9 c (рестарт + истечение аренды 20 c)
worker убит после COMMIT, до ack дубль = no-op redelivery → no-op, pending 0 0 c для пользователя
worker «завис» после истечения аренды задачу берёт другой reaper → attempt 2 → ready 37,3 c (аренда 20 c + ещё одна)
5 временных ошибок подряд failed retry_exhausted 22 c, задержки растут replay → ready
90 больших загрузок приём не ждёт обработку 90 × 202, p50 4,4–7,2 c (сама загрузка 9,6 МиБ) очередь разобрана за 103 c

Время восстановления после смерти worker определяется арендой: JOB_LEASE_SECONDS=20 c. Короче — быстрее восстановление, но выше риск перехватить живую задачу при паузе GC/диска. Heartbeat каждые 6,7 c даёт запас в 3 продления.

Порядок шагов в collect_evidence.py. Первый полный прогон уронил 4 унаследованных теста lab4: они скачивали файл сразу после ответа (теперь это 202, а не 201 ready), а persistence/failover стояли в очереди за 90 большими картинками от upload-memory. Тесты исправлены: ждут ready. Добавлен шаг queue-drain: ждёт пустой очереди перед persistence. В upload_memory.py критерий памяти теперь — память процессов (anon), без файлового кэша ядра. usage по-прежнему печатается: +68 МиБ, тоже меньше 100 МиБ.

Ответы на вопросы защиты

  • Publisher confirm vs consumer ack. Confirm — граница «брокер принял и сохранил»: у нас ответ XADD после fsync AOF. Ack (XACK) — граница «потребитель устойчиво выполнил работу»: у нас после COMMIT ready в PostgreSQL. Между ними сообщение лежит в PEL.
  • Что сохранено в момент 202. Полный проверенный оригинал в приватном staging/<id> (S3), строка attachments (queued), attachment_jobs и job_outbox — в одной транзакции. Сообщение в брокере — почти всегда, но не обязательно: если нет, его опубликует relay.
  • Почему повторная доставка нормальна и где ключ идемпотентности. At-least-once: сообщение повторяется, если ack не дошёл. Ключ эффекта — (attachment_id, pipeline_version, variant): PK attachment_variants + детерминированные ключи S3; логическая работа — job_id (UNIQUE по attachment_id, pipeline_version); устаревшие попытки отсекает attempt в сообщении.
  • Зависший или долгий. Долгий продлевает аренду heartbeat-ом; у зависшего она истекает. Захват — FOR UPDATE, фиксация — только с актуальным lease_token (fencing), поэтому два неконтролируемых исполнителя невозможны.

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

  • Задержка обработки под нагрузкой ограничена одним worker (1 CPU, 2 потока): ~0,9 больших картинки в секунду. Масштабирование — WORKER_REPLICAS; в этой работе не измерялось.
  • Брокер в одном экземпляре: отказ узла с брокером останавливает доставку (но не приём — outbox), реплики Redis/Sentinel не настроены.
  • appendfsync always дороже everysec; для учебной нагрузки это не узкое место, при большой нагрузке нужна оценка.
  • Relay и reaper работают в worker: если все worker выключены, отложенные retry ждут их запуска (новые задачи при этом публикует API).
  • Exactly-once нет и не обещается: at-least-once + идемпотентный эффект.