# Отчёт — лабораторная 5 - Автор, группа: [ФИО], [группа] - Целевая оценка; выбранный трек 5, если нужен: **5**, трек 1 «Очередь под перегрузкой» - Commit/PR: локальный коммит ветки `solution/lab5`; 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 перенесён. Использование ИИ: [заполняется автором] ## Запуск из чистого 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 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 # 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 # окна отказа, ~2.5 мин # операторские команды 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 ``` Windows: `scripts/restart.cmd`, `scripts/stop-one.cmd`. Остановка с сохранением данных — `docker compose --env-file .env stop`; **намеренное удаление учебных данных** — `down -v` (volumes `pgdata`, `valkeydata`, `seaweeddata`, `rabbitmqdata`). RabbitMQ 4.x объявил `RABBITMQ_DEFAULT_USER/PASS(_FILE)` устаревшими, поэтому учётные данные задаются конфигурационным файлом-секретом `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//… → ОДНА транзакция: варианты + 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/`, не локальный диск); метаданные и **намерение обработки** записаны одной транзакцией 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 `) допускается только для `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 (их отказ не должен останавливать приём/чтение). ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | | lab4 сохранён с переходом 201→202; smoke (thumbnail 256×160, SHA-256, размеры JPEG) | `tests/smoke.py` | PASS | `evidence/checks.txt` | | 202 только после устойчивого приёма; остановка API после ответа не теряет работу | `test_resilience5` №1, №4 | worker остановлен → upload 202 → сообщение с вложением → рестарт API → worker поднят → ready | `evidence/checks.txt` | | Broker и worker в стенде, durable, ack после эффекта; недоступность worker не заставляет API делать resize | описание; №1 | задание ждёт в `queued`, API ничего не обрабатывает | `evidence/checks.txt` | | Рестарт брокера с volume, принятое не исчезает | №2 | ready после рестарта RabbitMQ | `evidence/checks.txt` | | Брокер недоступен при приёме → outbox | №3 | 202 при остановленном брокере; в outbox 1 неопубликованная строка; после старта брокера — ready, outbox пуст | `evidence/checks.txt` | | Crash между COMMIT и publish | №4 (kill всех API при остановленном брокере) | задание доведено без ручного создания | `evidence/checks.txt` | | Остановка worker после записи в S3 до COMMIT / после COMMIT до ack | №5, №6 (`crash_once:…`) | lease истёк → задание завершено тем же результатом, `lease_expired`+`ready` в журнале; повторная доставка — no-op, вариантов по-прежнему 3 | `evidence/checks.txt` | | Ограниченный retry, backoff+jitter, failed, DLQ/реестр, replay | №7 | 3 попытки → `failed/retry_exhausted`, 2 события `retry_scheduled`; реестр содержит вложение; replay → ready; повторный replay → `skipped` | `evidence/checks.txt` | | Варианты по контракту, EXIF, alpha, без увеличения | `test_pipeline.py` (9 тестов) | thumbnail 256×160 / EXIF 100×300 → 85×256 / 50×30 не увеличивается; crop 128×128; WebP; alpha→белый; оригинал побайтно | `evidence/checks.txt` | | Повторная доставка не размножает варианты | `test_ready_job_redelivery…` | 3 варианта до и после | `evidence/checks.txt` | | Очистка staging | `test_staging_is_cleaned…` | staging готового удалён, failed — хранится | `evidence/checks.txt` | | Persistence/failover | `tests/resilience.py` | PASS ×3; `StartedAt` всех 7 сервисов изменился при рестарте | `evidence/checks.txt` | | **Трек 1** | `research/queue_overload.py` | см. ниже | `evidence/queue_overload.json\|png` | ## Эксперименты и отказы (трек 1) **Гипотеза.** Пропускная способность worker с ростом concurrency/prefetch увеличивается только пока есть свободный CPU и не растёт память; на крупных изображениях лишний параллелизм не ускоряет, но кратно увеличивает RSS и p95. Явный лимит принятой работы (backpressure) делает отказы предсказуемыми, а принятая работа не теряется; после разгрузки система принимает новые загрузки. **Методика** (`research/queue_overload.py`; Docker Desktop WSL2; worker **1 CPU / 768 MiB**; один процесс aiohttp, 8 клиентов-загрузчиков). Матрица 3 × 3: `WORKER_CONCURRENCY` ∈ {1, 2, 4} × изображения {small 320×200 PNG 109 КиБ ×80, medium 2400×1600 PNG 1.9 МиБ ×24, large 6000×4000 JPEG 3.0 МиБ ×12}; перед каждой ячейкой worker пересоздаётся (чистый пик RSS = `VmHWM`); очередь и возраст старейшего задания снимаются каждые 0.4 с; время до ready — `ready_at − accepted_at` из БД. | concurrency | small: throughput (готово/с) / p95 (с) / RSS (МиБ) | medium: throughput / p95 / RSS | large: throughput / p95 / RSS | | --- | --- | --- | --- | | 1 | 28.9 / 2.46 / 75 | 4.21 / 5.05 / 136 | 3.34 / 3.37 / 161 | | 2 | 43.7 / 1.60 / 76 | **4.71 / 4.69** / 194 | **3.77 / 2.96** / 254 | | 4 | **51.8 / 1.26** / 80 | 3.97 / 5.40 / 322 | 3.60 / 3.12 / 430 | Все 116 принятых файлов завершились `ready`, `failed` = 0, OOM-killer не срабатывал (пик 430 МиБ из 768). Пик глубины очереди/возраста старейшей задачи зависит от темпа приёма (≈20–66 заданий, до 5 с). Выводы: (1) для мелких файлов прирост от concurrency почти линейный (29 → 44 → 52/с: пока есть CPU); (2) для крупных изображений **оптимум — concurrency 2** (лучшие throughput и p95); при 4 процесс упирается в лимит 1 CPU и задержка растёт (medium: p95 4.69 → 5.40 с), а RSS растёт кратно (136 → 194 → 322 МиБ) — компромисс latency/ресурсы; (3) память масштабируется примерно как `concurrency × размер декодируемого изображения`, поэтому лимит памяти worker определяет допустимый prefetch для крупных файлов (рекомендация: `WORKER_CONCURRENCY=2` при 768 МиБ). **Backpressure и восстановление** (`MAX_QUEUED_JOBS=30`, worker concurrency 1, burst 200 мелких загрузок 32 клиентами за 0.5 с): принято **57**, отклонено **143** ответами `503 + Retry-After`; пик очереди 48 (превышение лимита на число одновременных проверок — проверка лимита выполняется до приёма и не является строгой блокировкой); все 57 принятых заданий завершились `ready` за 2.6 с (`failed` 0, потерь 0, p95 = 1.9 с); после разгрузки 3 новые загрузки приняты (восстановление). График: `evidence/queue_overload_backpressure.png`. **Ограничения методики.** Один ноутбук; лимит CPU worker 1.0 — часть результата (при большем CPU оптимум concurrency сместится); темп приёма ограничен клиентом (≈8 соединений), поэтому глубина очереди на крупных файлах невелика; повтор каждой ячейки не выполнялся (единичный прогон), различия <10 % (например, medium 2 vs 4) следует считать на границе погрешности; throughput средних/крупных файлов включает время приёма байт через API. ### Окна отказа (`contracts/attachment-states.md`) | Окно | Воздействие | Результат | | --- | --- | --- | | после staging до записи задания | сбой БД после записи в staging (lab4-механизм) | staging удаляется компенсацией; иначе reconcile (lab4) | | после 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) не реализовано. - Подтверждено экспериментами: оптимум concurrency для крупных изображений, рост памяти, backpressure и восстановление; гипотеза без доказательства: поведение при >1 worker и при другом лимите CPU.