30 KiB
Отчёт — лабораторная 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), Pythonresource(RLIMIT_AS/RLIMIT_CPU),multiprocessingforkserver; 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-streamattachments: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 аренда истекает. Тогда:
- сообщение из его PEL заберёт он сам после рестарта или другой worker (
XAUTOCLAIM, 90 c); обработку получит тот, кто первым увидит истёкшую аренду; - если за ещё одну аренду никто не перехватил, 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): PKattachment_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 + идемпотентный эффект.