forked from mtusi2026/mtusi2026lab5
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
153 lines
21 KiB
Markdown
153 lines
21 KiB
Markdown
# Отчёт — лабораторная 5
|
||
|
||
- Автор, группа: Боданюк Алексей, БВТ2302
|
||
- Целевая оценка; трек 5: **5**, трек 2 «Доказанная идемпотентность pipeline»
|
||
- Commit/PR: ветка `solution/bvt2302-bodanyuk`; PR «ЛР 5 — БВТ2302 — Боданюк — на 5» (ссылка после публикации)
|
||
- Источники, библиотеки, ИИ: Python 3.13, Starlette, uvicorn, psycopg 3, redis-py, argon2-cffi, aiobotocore (из ЛР 2–4); новое: **aio-pika 9.6.2** (AMQP), **Pillow 12.3.0** (варианты, только в worker). Документация: [RabbitMQ reliability](https://www.rabbitmq.com/docs/reliability), [confirms](https://www.rabbitmq.com/docs/confirms), [quorum queues](https://www.rabbitmq.com/docs/quorum-queues), AWS «Exponential Backoff And Jitter». Код, тесты и документы написаны с помощью ИИ-ассистента (Claude); архитектурные решения разобраны и объяснимы автором (см. [docs/DEFENSE.md](docs/DEFENSE.md)).
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Версии (всё по тегу **и** digest, см. [compose.yaml](compose.yaml)): Python 3.13.16-slim-bookworm, PostgreSQL 18.6, Valkey 8.1.3, SeaweedFS 4.46, **RabbitMQ 4.3.7-alpine**, HAProxy 3.2.26. Python-пакеты — `requirements.txt` с sha256-хешами (`pip install --require-hashes --no-deps`).
|
||
|
||
Prerequisites: Docker с Compose v2, Python 3.12+, Git; на Windows — [docs/WINDOWS.md](docs/WINDOWS.md).
|
||
|
||
```sh
|
||
git clone <fork> mtusi2026lab5 && cd mtusi2026lab5 && git checkout solution/bvt2302-bodanyuk
|
||
python3 scripts/init_secrets.py # ./secrets: пароли БД/Valkey, 4 пары S3, пользователи RabbitMQ (хеши), URL брокера
|
||
cp .env.example .env
|
||
docker compose --env-file .env config --quiet
|
||
docker compose --env-file .env up -d --build --wait # migrate и s3-init — один раз, exit 0; остальные healthy
|
||
make check test # Windows: $env:PYTHONUTF8="1"; make ... PYTHON=python
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh && make restore
|
||
python3 -m venv .venv && .venv/bin/pip install --require-hashes --no-deps -r requirements.txt && .venv/bin/pip install -r requirements-test.txt
|
||
.venv/bin/python scripts/demo_pipeline.py # сценарий защиты, шаги 2-3
|
||
.venv/bin/python -m pytest student-tests -v
|
||
.venv/bin/python bench/pipeline_faults.py --output evidence/track2
|
||
make audit # инварианты, read-only
|
||
```
|
||
|
||
Всё это одной командой на чистом clone: `python scripts/collect_evidence.py` (вывод — в `evidence/`). Действий оператора нет. Безопасная остановка: `docker compose down` (volumes остаются). Намеренное удаление учебных данных: `docker compose down -v` и удалить `./secrets`.
|
||
|
||
## Архитектура и решения
|
||
|
||
```text
|
||
client ─▶ lb (HAProxy) ─▶ api ×2 ──▶ postgres (метаданные, jobs, outbox, попытки, аудит) [data]
|
||
├──▶ valkey (сессии) [data]
|
||
└──▶ s3: messenger-staging (Write) / messenger-attachments (Read) [storage]
|
||
relay ──▶ postgres (outbox, reaper) ──▶ broker (RabbitMQ, quorum queue + DLQ) [data, queue]
|
||
worker ◀── broker; ──▶ postgres; ──▶ s3 (Read/Write оба bucket) [data, storage, queue]
|
||
```
|
||
|
||
- **Источник истины — PostgreSQL**, включая работу: состояние, попытки, lease, время повтора, реестр failed. Брокер доставляет только `job_id`; ack — после COMMIT результата. Подробно — [docs/PIPELINE.md](docs/PIPELINE.md); схема — [docs/DATA_MODEL.md](docs/DATA_MODEL.md).
|
||
- **Транзакционные границы.** Upload: `pending` → PUT staging → **одна транзакция** `queued + jobs + outbox` → 202. Результат: **одна транзакция** `attachment_variants ×3 + attachments ready` с проверкой `lease_token` → ack.
|
||
- **API не связан с брокером** (нет сети `queue`, нет учётных данных). Недоступность worker/брокера не делает resize синхронным и не ломает upload.
|
||
- **Перенесено из lab4 без изменений** (коммит `5112be8`): API, сессии, идемпотентность сообщений, HAProxy с активной readiness, лимиты загрузки, PNG-валидатор и `djpeg -strict`, janitor `pending`, graceful shutdown, тесты.
|
||
- **Изменено:** upload 201 → 202; GET метаданных видит `queued/processing/failed`; `content` → 409 до ready, варианты `thumbnail/crop/optimized`; к сообщению можно прикрепить `queued/processing` (`post_message_v3`), `failed` → 409; S3 разделён на два bucket и четыре identity; restart-хук перезапускает и broker/relay/worker.
|
||
- **Убрано:** reconciler lab4 (трек прошлой лабы, не обязательный минимум). В lab5 мусор находится по журналу `job_attempts.planned_keys` без права List; аудит `messenger.audit` проверяет оба bucket read-only-ключом. Удаление файлов reconciler попало в коммит `a633949`, а не в `bc32a50`, где об этом сказано, — ошибка при разбиении коммитов, историю не переписывал.
|
||
- **Ограничения доступа.** S3: api — Write staging + Read final; worker — Read/Write оба; auditor — Read+List; admin — только `s3-init`. RabbitMQ: `relay` — только write в exchange `messenger.jobs`, `worker` — только read очереди, configure ни у кого; `guest` нет; management UI и Prometheus выключены. Проверяется `s3-init` при каждом старте и тестом `test_compose_policy_limits_ports_secrets_images`.
|
||
|
||
### Соответствие `.env.example`
|
||
|
||
| Переменная | Значение | Где |
|
||
| --- | --- | --- |
|
||
| `BROKER_URL_FILE` | `/run/secrets/broker_url` | relay и worker, у каждого свой пользователь RabbitMQ |
|
||
| `S3_STAGING_BUCKET` | `messenger-staging` | api, worker, s3-init, auditor |
|
||
| `WORKER_CONCURRENCY` | 2 | prefetch и число дочерних процессов worker |
|
||
| `JOB_MAX_ATTEMPTS` | 5 | claim-ов на задание (пишется в задание при создании) |
|
||
| `JOB_TIMEOUT_SECONDS` | 60 | потолок одной попытки (kill процесса, конец продления lease) |
|
||
| `JOB_LEASE_SECONDS` | 30 | lease, heartbeat каждые 10 с |
|
||
| `JOB_RETRY_BASE_SECONDS` / `_MAX_` | 2 / 60 | full jitter |
|
||
| `STAGING_RETENTION_SECONDS` | 86400 | хранение staging у `failed` для replay (у `ready` удаляется сразу) |
|
||
| `ORPHAN_GRACE_SECONDS` | 600 | удаление объектов неуспешных попыток |
|
||
| `IMAGE_MAX_MEMORY_MB` | 768 | RLIMIT_AS дочернего процесса |
|
||
| `PIPELINE_VERSION` | 1 | версия заданий новых загрузок (1, 2, 3 в `pipeline.py`) |
|
||
| `API_/RELAY_/WORKER_FAULT_POINTS` | пусто | внедрение отказов только для экспериментов |
|
||
| `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS` | 10485760, 40000000 | API (до чтения тела) и worker (до скачивания/декодирования) |
|
||
|
||
## Доказательства критериев
|
||
|
||
Все файлы — из прогона `scripts/collect_evidence.py` на **чистом clone** (новые secrets, пустые volumes), см. раздел «Финальный прогон».
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл |
|
||
| --- | --- | --- | --- |
|
||
| Публичный smoke | `make check test` | PASS lab5: 202 → ready, JPEG 256×160 | [make-check-validate-test.txt](evidence/make-check-validate-test.txt) |
|
||
| **3:** минимум lab4 сохранён, 201 → 202 | `pytest student-tests` (test_api, test_attachments, test_idempotency, test_balancing, test_sessions, test_failures) | все проходят, 415 на все кейсы рецензий (PNG фильтр 5/0xff, IDAT не zlib, JPEG 27 байт, SOS не из SOF) | [student-tests.txt](evidence/student-tests.txt) |
|
||
| **3:** 202 только после устойчивого приёма; остановка API не теряет | test_consistency (`after_s3_put`, `after_enqueue_commit`), demo | окно «после staging» — невидимый `pending`, убран janitor; после COMMIT — ready | student-tests.txt |
|
||
| **3:** отдельные broker и worker, durable, ack после эффекта | compose, `rabbitmqctl list_queues`; `test_worker_crash_after_commit…` | quorum queue durable; redelivery → `noop_finished` | [clean-clone.txt](evidence/clean-clone.txt), student-tests.txt |
|
||
| **3:** worker недоступен → API не делает resize | `test_worker_stopped…`, demo | 202 queued, content 409, сообщения 201 | [demo-pipeline.txt](evidence/demo-pipeline.txt) |
|
||
| **3:** состояния queued/processing/ready/failed, thumbnail по контракту | test_pipeline_flow (`check_variants`) | реальные размеры через Pillow, sha256 = метаданные, оригинал побайтно | student-tests.txt |
|
||
| **3:** ограниченный retry, failed + error_code; повтор не плодит варианты | `test_retry_exhausted…`, `test_duplicate…` | 5 попыток → `retry_exhausted`; дубли → 1 набор | student-tests.txt |
|
||
| **3:** демонстрация stop worker → 202 → сообщение → restart API (+broker) → ready | `scripts/demo_pipeline.py` | очередь `messages=1` до и после рестарта брокера, ready, одна попытка | demo-pipeline.txt |
|
||
| Persistence / failover (публичные) | `make test-persistence`, `make test-failover` | PASS, состояния контейнеров до/после | [test-persistence.txt](evidence/test-persistence.txt), [test-failover.txt](evidence/test-failover.txt) |
|
||
| **4:** crop 128 и WebP 1280, параметры | unit test_pipeline + check_variants | геометрия, EXIF, alpha, без метаданных — [PIPELINE.md](docs/PIPELINE.md#варианты) | student-tests.txt |
|
||
| **4:** лимиты bytes/пикселей/времени/памяти worker | `test_memory_and_time_limits_of_the_worker`, `test_exactly_40_megapixels…` | 40 Мпикс при 200 МБ → `image_too_large`; 3 с → `processing_timeout`; 40 Мпикс в 768 МБ → ready | student-tests.txt |
|
||
| **4:** outbox; crash между COMMIT и publish | `test_broker_down…`, `test_relay_down…`, `test_crash_after_publish…` | строка outbox ждёт, публикуется без ручных действий | student-tests.txt |
|
||
| **4:** backoff с jitter, постоянные/временные | `test_transient_errors…`, `test_permanent_error…` | задержки в `[0, base·2^(n−1)]`, invalid_image — 1 попытка | student-tests.txt |
|
||
| **4:** DLQ/реестр failed, безопасный replay | `jobctl list-failed/replay`, `test_bad_message…` | replay → ready; replay готового → `already_ready`; плохое сообщение → DLQ | student-tests.txt |
|
||
| **4:** crash после записи объекта до ack | `test_worker_crash_after_s3_write…`, `…after_commit…` | один опубликованный набор, мусор попытки 1 удалён | student-tests.txt |
|
||
| **4:** lease зависшего processing, prefetch, очистка staging | `test_hung_worker…` (docker pause), `test_concurrency…`, `test_queued_staging…`, `test_cleanup_racing…` | попытки `[abandoned, succeeded]`; ≤2 processing; staging `queued` не удаляется, CHECK отвергает | student-tests.txt |
|
||
| **5, трек 2** | `bench/pipeline_faults.py`, `make audit` | см. ниже | [evidence/track2/](evidence/track2/), [track2-runs.txt](evidence/track2-runs.txt) |
|
||
|
||
## Эксперименты и отказы
|
||
|
||
### Трек 2: доказанная идемпотентность versioned pipeline
|
||
|
||
**Гипотеза.** При at-least-once доставке, дублях и переупорядочивании сообщений, crash worker до/после побочного эффекта и устаревших заданиях старой версии pipeline: (H1) ни одна принятая 202 работа не теряется; (H2) каждый эффект `(attachment, version, variant)` опубликован ровно один раз; (H3) опубликованная версия только растёт, `ready` не откатывается; (H4) мусор прерванных попыток удаляется, опубликованное не удаляется никогда.
|
||
|
||
**Механизм.** Ключ эффекта — PK `attachment_variants`; ключи объектов включают токен попытки; fencing `lease_token` при каждом COMMIT; монотонный `published_version`; claim по состоянию задания в БД; уборка только по `planned_keys` неуспешных попыток под блокировкой.
|
||
|
||
**Методика** ([bench/pipeline_faults.py](bench/pipeline_faults.py)). Для каждого сценария пересоздаётся один сервис с `FAULT_POINTS` (реальные пути кода, реальный `os._exit`, реальный `docker pause`), N загрузок через LB, затем читаются факты из PostgreSQL и S3 (List auditor-ключом), а в конце аудит `I1–I7` с проверкой SHA-256 всех опубликованных объектов по всему стенду.
|
||
|
||
| Сценарий | Внедрение |
|
||
| --- | --- |
|
||
| baseline | — |
|
||
| дубль | relay публикует каждое сообщение дважды |
|
||
| дубль + reorder | дважды и в обратном порядке пачки |
|
||
| crash relay после confirm до отметки | `os._exit` relay |
|
||
| crash worker до побочного эффекта | `os._exit` после claim |
|
||
| crash worker после S3 до COMMIT | `os._exit` после PUT объектов |
|
||
| crash worker после COMMIT до ack | `os._exit` после COMMIT |
|
||
| временные ошибки | 2 неудачные попытки |
|
||
| 2 worker + дубль | конкурирующие потребители |
|
||
| устаревшая версия | reprocess v2 (медленный) и v3 одновременно; затем вручную опубликованный дубль задания v1 |
|
||
| reorder версий в очереди | v2 и v3 в outbox, relay публикует в обратном порядке, 1 worker |
|
||
| зависший worker | 2 worker, `docker pause` владельца lease |
|
||
|
||
**Результаты:** РЕЗУЛЬТАТЫ_ТРЕКА_2
|
||
|
||
**Почему это не exactly-once.** Доставка остаётся at-least-once: в сценариях дубля в очереди физически два сообщения, а у зависшего worker вычисление выполнялось дважды (попытки `abandoned` и `succeeded`). Exactly-once — только у **видимого эффекта**, за счёт ключа эффекта, fencing и монотонной версии. Чего нет: (1) защиты от двух независимых **сред** с разными БД; (2) гарантии при потере диска одного Docker-хоста (quorum queue и PostgreSQL на одном узле); (3) удаления опубликованных вариантов старых версий — они остаются (rollback-кандидаты), удаляются только неопубликованные.
|
||
|
||
### Отказы
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Восстановление / потеря |
|
||
| --- | --- | --- | --- |
|
||
| worker остановлен, upload | 202, content 409, сообщения работают | так и есть | после старта worker → ready, 0 потерь |
|
||
| restart API + broker с volumes | сообщение остаётся в quorum queue | `messages=1` до и после | 0 потерь |
|
||
| broker остановлен | upload 202, outbox ждёт | `published=False`, текст работает | relay публикует после возврата брокера |
|
||
| relay остановлен | outbox ждёт | так и есть | ready после старта |
|
||
| crash relay после confirm | дубль в очереди | один claim, один набор | 0 дублей эффекта |
|
||
| crash worker после claim / S3 / COMMIT | lease → reaper → попытка 2; либо no-op | `[abandoned, succeeded]`; мусор удалён | lease 6 с в тесте (30 с по умолчанию) + ≤5 с reaper |
|
||
| docker pause worker с lease | второй worker публикует, первый fenced | так и есть | ≤ lease + 5 с + AMQP heartbeat |
|
||
| 5× временная ошибка | `failed/retry_exhausted` → replay → ready | так и есть | replay оператора |
|
||
| уборка vs replay (пауза в уборке) | staging не удалён | ready, staging удалён только после ready | — |
|
||
| S3 остановлен/заморожен (lab4) | readiness 503, upload 503 < 8 с, текст работает | так и есть | файлы целы |
|
||
|
||
**Дефекты, найденные в ходе работы и исправленные:**
|
||
1. После рестарта брокера worker оставался без consumer, а healthcheck показывал healthy; relay падал на `ChannelInvalidStateError`. Причина: aio-pika не выставляет `is_closed` при закрытии соединения сервером. Исправлено (`1d37fd0`): `close_callbacks`, heartbeat-файл только при живом consumer.
|
||
2. Внедрённый crash worker срабатывал на каждой попытке, а не один раз на задание. Исправлено там же.
|
||
3. Аудит ошибочно требовал объект staging у `pending` (PUT мог не пройти). Исправлен инвариант I5.
|
||
|
||
### Окружение и лимиты
|
||
|
||
Ноутбук: AMD Ryzen 5 3400G (4 ядра / 8 потоков), 29,9 ГБ RAM, Windows 10 Enterprise 19045, Docker Desktop 29.8.0 (VM: 8 CPU, 15,7 ГБ). Лимиты контейнеров (фактические, `docker inspect` в clean-clone.txt): api 1 CPU / 512m ×2, worker 2 CPU / 1536m (без swap), broker 1 CPU / 512m, relay 0,5 / 256m, postgres 2 / 1g, s3 1 / 1g, valkey 0,5 / 256m, lb 1 / 128m, migrate/s3-init 0,5 / 256m, auditor 1 / 256m, jobctl 0,5 / 128m. Нагрузочных выводов о производительности в этой лабе не делается (трек 2 — про корректность); `tests/load.py` приложен как контроль регрессии lab3.
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
- Один Docker-хост: quorum queue на одном узле (без репликации), PostgreSQL один. «Устойчиво» = переживает рестарт процессов/контейнеров с volumes.
|
||
- SeaweedFS подтверждает PUT без явного fsync каждой записи; потеря питания хоста — вне модели угроз.
|
||
- Опубликованные варианты старых версий не удаляются; квоты на число версий нет.
|
||
- Колонки карантина lab4 (`lost_at`) сохранены, но ничем не выставляются (reconciler удалён).
|
||
- Объект, записанный замороженной попыткой **после** её уборки (пауза дольше `ORPHAN_GRACE_SECONDS`), станет мусором; аудит покажет его как `leaked_object`. Это не потеря: опубликованное не задевается.
|
||
- Следующие шаги: трассировка (`traceparent` в сообщении уже предусмотрен схемой) — lab6.
|