Files
mtusi2026lab5/REPORT.md
T

116 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 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 <attachment_id>
```
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/<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 (их отказ не должен останавливать приём/чтение).
## Доказательства критериев
| Критерий 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.