docs: PIPELINE, DEFENSE, DATA_MODEL, WINDOWS для lab5; черновик REPORT

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Alexey Bodanyuk
2026-10-31 17:17:17 +03:00
co-authored by Claude Opus 5.5
parent e453ee2312
commit cf6e92957c
5 changed files with 479 additions and 17 deletions
+132 -17
View File
@@ -1,37 +1,152 @@
# Отчёт — лабораторная 5
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: Боданюк Алексей, БВТ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
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Версии (всё по тегу **и** 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`.
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab4, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
```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 (до скачивания/декодирования) |
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
Все файлы — из прогона `scripts/collect_evidence.py` на **чистом clone** (новые secrets, пустые volumes), см. раздел «Финальный прогон».
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
| Критерий 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) |
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
### Трек 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-кандидаты), удаляются только неопубликованные.
### Отказы
| Воздействие | Что ожидаем | Что наблюдали | Восстановление / потеря |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
| 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.
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
- Один Docker-хост: quorum queue на одном узле (без репликации), PostgreSQL один. «Устойчиво» = переживает рестарт процессов/контейнеров с volumes.
- SeaweedFS подтверждает PUT без явного fsync каждой записи; потеря питания хоста — вне модели угроз.
- Опубликованные варианты старых версий не удаляются; квоты на число версий нет.
- Колонки карантина lab4 (`lost_at`) сохранены, но ничем не выставляются (reconciler удалён).
- Объект, записанный замороженной попыткой **после** её уборки (пауза дольше `ORPHAN_GRACE_SECONDS`), станет мусором; аудит покажет его как `leaked_object`. Это не потеря: опубликованное не задевается.
- Следующие шаги: трассировка (`traceparent` в сообщении уже предусмотрен схемой) — lab6.
+57
View File
@@ -0,0 +1,57 @@
# Модель данных lab5
Схема: [0001_init.sql](../migrations/0001_init.sql) (lab2), [0002_idempotency_keys.sql](../migrations/0002_idempotency_keys.sql) и [0003_post_message_function.sql](../migrations/0003_post_message_function.sql) (lab3), [0004_attachments.sql](../migrations/0004_attachments.sql) (lab4), [0005_pipeline.sql](../migrations/0005_pipeline.sql) (lab5: задания, outbox, попытки, варианты). Миграции применяет один раз отдельный сервис `migrate` до старта реплик API; миграции lab3–lab5 только добавляют объекты (0004 ослабляет `CHECK` длины текста, 0005 — `CHECK` статуса и ключа объекта), поэтому совместимы с работающей предыдущей версией. Байты вложений живут **только** в двух приватных bucket S3 (SeaweedFS): `messenger-staging` (оригинал до обработки) и `messenger-attachments` (опубликованный оригинал и варианты); в PostgreSQL — метаданные, задания и их история. Порядок записи и окна отказа — [PIPELINE.md](PIPELINE.md). Источник истины для пользователей, чатов, участников и сообщений — PostgreSQL 18. Для сессий источник истины — хранилище, выбранное через `SESSION_STORE`. По умолчанию это Valkey с AOF, его можно переключить на таблицу `sessions` в PostgreSQL.
## Таблицы и ограничения
| Таблица | Ключ | Ограничения | Зачем |
| --- | --- | --- | --- |
| `users` | `id uuid` | `UNIQUE (username)`, `CHECK` формата username, длина `display_name` | уникальность имени держит БД, а не код: гонку регистрации разрешает уникальный индекс |
| `chats` | `id uuid` | FK `created_by → users`, длина `title` | `last_message_at` — «часы» чата для упорядочивания сообщений |
| `chat_members` | `(chat_id, user_id)` | FK на `chats` и `users`, `UNIQUE (chat_id, position)` | `position` хранит порядок `member_ids`; `chat_created_at` — копия времени чата для keyset-списка чатов |
| `messages` | `id uuid` | FK `(chat_id, sender_id) → chat_members`, длина `text` | отправитель обязан быть участником — это гарантирует сама БД |
| `sessions` | `token_hash bytea` | FK `user_id → users`, длина хеша 32 байта | хранится SHA-256 токена; сам токен не хранится нигде |
| `idempotency_keys` | `(user_id, chat_id, key)` | FK на `users`, `chats`; `message_id → messages` (DEFERRABLE, `UNIQUE`); `CHECK` формата ключа и длины SHA-256 | общая для всех реплик идемпотентность отправки: ключ → отпечаток тела → сообщение. Хранится ≥ `IDEMPOTENCY_TTL_SECONDS` (24 ч), очистка — пачками раз в 10 мин под advisory-замком |
| `attachments` (lab4, lab5) | `id uuid` | FK `(chat_id, owner_id) → chat_members`; `UNIQUE object_key`, `UNIQUE staging_key` (`COLLATE "C"`); `CHECK` статуса `pending/queued/processing/ready/failed`, формата ключей, типа, размера, пикселей ≤ 40 млн; **`attachments_active_has_source`**: у `queued/processing` есть опубликованный оригинал или staging `present`; `ready` ⇒ `object_key` и `published_version`; `failed` ⇔ `error_code` + `failed_at` | метаданные оригинала. `staging_key` (`s/<128 бит>`) — копия в staging, `staging_state none/present/deleting/deleted`; `object_key` — опубликованный оригинал (`a/<id>/<token>/original`, у строк lab4 — `o/<hex>`). `published_version` — версия pipeline, чьи варианты видны, только растёт |
| `jobs` (lab5) | `id uuid` = job_id | FK на `attachments`; `CHECK` состояния, вида (`upload/replay/reprocess/migrate`), `attempt ≤ max_attempts`, lease есть ⇔ `processing`, `finished_at` ⇔ конечное; частичный `UNIQUE (attachment_id, pipeline_version) WHERE state IN ('queued','processing')` | одна логическая работа «версия V для вложения A». `available_at` — backoff, `lease_token`/`lease_until`/`lease_owner` — аренда текущей попытки (fencing). Индексы: истекающие lease, queued, failed |
| `job_attempts` (lab5) | `token uuid` | FK на `jobs`; `UNIQUE (job_id, attempt)`; `CHECK` исхода `running/succeeded/retry/failed/abandoned/superseded`; опубликованную попытку нельзя «почистить» | один claim worker. `planned_keys` — ключи всех объектов попытки, записаны ДО записи в S3: уборке не нужен List. Частичный индекс — кандидаты на уборку |
| `attachment_variants` (lab5) | `(attachment_id, pipeline_version, name)` | FK на `attachments`, `job_attempts`; `UNIQUE object_key`, `CHECK` имени, типа, размера, длины SHA-256 | опубликованные варианты; первичный ключ — ключ эффекта контракта, дубль физически невозможен |
| `outbox` (lab5) | `id bigint` identity | FK на `jobs`; `attempt ≥ 1` | намерение опубликовать сообщение; пишется в одной транзакции с изменением задания. Частичный индекс `WHERE published_at IS NULL` — работа relay |
| `job_events` (lab5) | `id bigint` identity | FK на `jobs` | аудит: создание, claim, retry с задержкой, lease_expired, replay/reprocess (оператор и причина), результат, внедрённые отказы. Без секретов и имён файлов. View `failed_jobs` — реестр failed |
| `message_attachments` (lab4) | `(message_id, position)` | FK на `messages` и `attachments`, `UNIQUE (message_id, attachment_id)`, индекс по `attachment_id` | целостность ссылок (вложение, на которое ссылается сообщение, удалить нельзя) и обратный поиск «используется ли вложение» |
| `schema_migrations` | `version` | checksum файла | какие миграции применены; изменённую задним числом миграцию мигратор не применит |
**Почему `bytea` для текста.** Контракт разрешает символ U+0000, а тип `text` в PostgreSQL не может содержать байт NUL (`DataError`). Поэтому `display_name`, `title` и `text` хранятся как байты UTF-8. Длину в code points проверяет API, а `CHECK` в байтах — страховка (1 code point ≤ 4 байта).
## Индексы и запросы
- `messages_chat_keyset (chat_id, created_at, id)`. Первая страница — `WHERE chat_id=$1 ORDER BY created_at, id LIMIT n`, следующая — `WHERE chat_id=$1 AND (created_at, id) > ($2, $3) ORDER BY ... LIMIT n`. Сравнение строк `(created_at, id) > (...)` попадает в `Index Cond`: поиск начинается прямо с позиции cursor и читает только `n+1` строк. Запросов два, а не один с `($2 IS NULL OR ...)`: иначе при generic plan условие cursor уходит в `Filter`, и поздняя страница сканирует всю историю чата до неё.
- `chat_members_user_keyset (user_id, chat_created_at, chat_id)` — список чатов пользователя тем же keyset-способом.
- `users_username_key` — вход по username и уникальность.
- `sessions_expires_at` — очистка истёкших сессий.
## Транзакционные границы
| Операция | Транзакция | Что гарантирует |
| --- | --- | --- |
| Регистрация | один `INSERT` | `UniqueViolation` → 409; ровно одна строка при гонке |
| Создание чата | `INSERT chats` → `INSERT chat_members` (все участники одним запросом) → `COMMIT` | неизвестный участник вызывает FK-ошибку **после** вставки чата; откат удаляет и чат, и частичное членство |
| Сообщение (lab3, с ключом) | проверка членства → `INSERT idempotency_keys … ON CONFLICT DO UPDATE … WHERE ключ старше 24 ч` → если вставлен: `UPDATE chats … RETURNING` → `INSERT messages`; если нет: прочитать сохранённое сообщение и сравнить отпечаток → `COMMIT`. По умолчанию всё это — одна SQL-функция `post_message` в autocommit (одно обращение к БД) | ключ, сообщение и «результат» коммитятся вместе или не коммитятся вовсе: «висящего» ключа нет. Конкурентный повтор ждёт на уникальном индексе завершения первой транзакции и затем видит её результат (READ COMMITTED, новый снимок на каждый оператор). Другое тело → 409, тот же — тот же Message |
| Сообщение с `attachment_ids` (lab4, lab5) | функция `post_message_v3` (0005): проверка членства → проверка вложений (этого чата, не `pending`; `failed`/карантин → 409; `FOR SHARE`) → только если всё хорошо — захват ключа → `UPDATE chats` → `INSERT messages (…, attachment_ids)` → `INSERT message_attachments` | чужое/неизвестное/незавершённое вложение — 404, в карантине — 409, ключ при этом не «сгорает». Порядок `attachment_ids` хранится массивом в строке сообщения: страница истории остаётся одним диапазонным сканом индекса |
| Загрузка вложения (lab5) | `INSERT attachments … 'pending'` (autocommit) → S3 PUT в staging (Content-MD5) → **одна транзакция**: `UPDATE … SET status='queued' WHERE status='pending'` + `INSERT jobs` + `INSERT outbox` + `INSERT job_events` → 202 | 202 только когда оригинал в staging и задание с outbox зафиксированы. Сбой до COMMIT оставляет невидимый `pending`, его убирает janitor. Компенсации в обработчике нет |
| Claim (worker) | `SELECT jobs … FOR UPDATE` → решение (no-op / superseded / работа) → `SELECT attachments … FOR UPDATE` → `UPDATE jobs` (processing, attempt+1, lease, token) + `INSERT job_attempts` + `UPDATE attachments` (processing) + событие | дубль доставки видит конечное состояние или чужой lease и ничего не делает |
| Результат (worker) | `SELECT jobs … FOR UPDATE` (проверка токена) → `SELECT attachments … FOR UPDATE` → если версия не новее опубликованной: `superseded`; иначе `INSERT attachment_variants` ×3 + `UPDATE attachments` (ready, published_version, object_key) + `UPDATE jobs/job_attempts` + событие → потом ack | результат публикуется атомарно и только владельцем текущей аренды; версия только растёт |
| Retry / failed (worker), lease (relay) | под блокировкой задания: попытка `retry`/`failed`/`abandoned`; задание `queued` с `available_at` + новая строка outbox, или `failed` (реестр) | повтор идёт тем же путём outbox; бесконечного немого retry нет |
| Replay / reprocess (jobctl), уборка staging | `SELECT attachments … FOR UPDATE` (одна и та же блокировка) → проверки → новое задание + outbox, либо `staging_state='deleting'` | уборка и replay сериализованы строкой вложения |
| Порядок блокировок | везде, где нужны обе строки: сначала `jobs`, потом `attachments` | нет взаимных ожиданий в разном порядке |
| Сообщение (lab2-часть) | проверка членства → `UPDATE chats SET last_message_at = greatest(clock_timestamp(), last_message_at + 1 мкс) RETURNING` → `INSERT messages` → `COMMIT` | строка чата заблокирована до конца транзакции, поэтому писатели одного чата идут по очереди. Время сообщений строго растёт **в порядке коммитов**: страница по cursor не пропустит сообщение, закоммиченное «задним числом» |
| Вход | `SELECT` пользователя, проверка Argon2id, запись сессии | неверный пароль ничего не пишет |
| Logout | `DELETE` сессии (или `DEL` в Valkey) | повтор с тем же токеном — 401 |
Чтение истории не требует snapshot между HTTP-запросами (так в контракте): новое сообщение появится на следующей странице. Список чатов сортируется по `chats.created_at = clock_timestamp()` без блокировки. Два чата, создаваемые одновременно, могут закоммититься не в порядке времени. Тогда у обхода, который уже начался, такой чат может оказаться «до» cursor; новый обход его увидит. Чаты создаются редко, поэтому мы не сериализуем их глобальным замком; это ограничение описано в REPORT.md.
## Сессии
- Токен: `secrets.token_urlsafe(32)` — 256 бит случайности, в ответе 43 символа. В хранилище лежит только SHA-256 токена. Для случайного 256-битного значения быстрого хеша достаточно, медленный KDF нужен только для низкоэнтропийных паролей.
- `SESSION_STORE=valkey` (по умолчанию): ключ `session:<sha256-hex>`, значение `{user_id, expires_at}`. Срок жизни задаётся абсолютным `PXAT expires_at`, поэтому рестарт его не продлевает. Включён `appendonly yes` + `appendfsync always`: подтверждённые вход и logout сохраняются до ответа клиенту. Valkey — **единственное** хранилище сессий, это не кэш над PostgreSQL. Поэтому нет второй копии, которая могла бы «оживить» отозванный токен после отказа. Если Valkey недоступен, проверить сессию нельзя: защищённые запросы и logout получают 503, анонимный доступ не открывается.
- `SESSION_STORE=postgres`: таблица `sessions`, проверка `expires_at > now()` в запросе.
+48
View File
@@ -0,0 +1,48 @@
# Ответы на вопросы защиты ЛР 5
Подробности и схемы: [PIPELINE.md](PIPELINE.md). Тесты: [test_pipeline_flow.py](../student-tests/test_pipeline_flow.py), [test_consistency.py](../student-tests/test_consistency.py), трек 2: [bench/pipeline_faults.py](../bench/pipeline_faults.py).
## Чем publisher confirm отличается от consumer ack?
- **Publisher confirm** — ответ брокера **отправителю** (у нас relay): «сообщение принято и записано в quorum-очередь на диск». Без confirm relay не знает, дошло ли сообщение, поэтому строку outbox он помечает `published_at` только после confirm. `mandatory=True`: если сообщение некуда положить, брокер вернёт его, и это будет ошибка, а не тихая потеря.
- **Consumer ack** — ответ **потребителя** (worker) брокеру: «можно удалить сообщение, работа сделана». Worker шлёт ack только после COMMIT результата в PostgreSQL. Если упасть до ack, брокер отдаст сообщение снова.
- Это две разные границы. Confirm говорит «намерение надёжно лежит в очереди», ack — «эффект надёжно сохранён». Между ними могут пройти часы (worker остановлен), и сообщение всё это время лежит в quorum log на volume `rabbitmqdata`. Тест: worker остановлен → upload 202 → relay публикует (confirm) → рестарт брокера → сообщение на месте → worker стартует → ack после ready.
## Что именно уже сохранено в момент 202?
1. **Оригинал** — полностью и уже проверенный (лимиты, PNG/JPEG-валидаторы, 413/415 решаются до записи), в приватном bucket `messenger-staging`. S3 подтвердил PUT с Content-MD5.
2. **Метаданные + задание + строка outbox** — одной транзакцией PostgreSQL: вложение `queued`, `jobs` (`queued`, attempt 0), `outbox`.
Чего ещё нет: варианта, опубликованного оригинала, сообщения в брокере (его отправит relay). После 202 можно убить API — ничего не пропадёт. Если брокер лежит, upload всё равно 202: API с брокером вообще не связан. Сбой **до** COMMIT задания (окно «после staging») 202 не даёт: клиент получает 503, строка `pending` невидима, janitor убирает staging и строку (test_consistency).
## Почему повторная доставка нормальна и где ключ идемпотентности job?
- Гарантия at-least-once неизбежна: relay может упасть после confirm, но до отметки в outbox; worker может упасть после COMMIT, но до ack; соединение рвётся. Сообщение придёт ещё раз — это не ошибка, а цена того, что мы его не теряем.
- **Ключ идемпотентности задания — `jobs.id` (job_id) в PostgreSQL.** Каждая доставка начинается с `claim` под `SELECT … FOR UPDATE` строки задания: `succeeded` → ack без работы; `processing` с живым lease → ack (его судьбу решит reaper); backoff не истёк → ack. Попадание в работу возможно только из `queued`.
- **Ключ эффекта — `(attachment_id, pipeline_version, variant)`**: первичный ключ `attachment_variants`. Объекты пишутся под ключами своей попытки (`a/<id>/<token>/thumbnail`); опубликовано ровно то, на что ссылается один COMMIT. Дубль не создаёт второго набора, а мусор прерванных попыток удаляет уборка.
- Это не exactly-once доставка: работа может выполниться дважды (зависший worker досчитает). Exactly-once только у видимого результата.
## Как отличить зависший worker от долго работающего и не запустить два неконтролируемых дубля?
- **Lease с heartbeat.** Claim даёт попытке `lease_until = now + 30 s` и случайный `lease_token`. Живой worker продлевает lease каждые 10 с (`UPDATE … WHERE lease_token = мой`). Долго работающий продлевает, зависший — нет.
- **Потолок времени.** Даже живой heartbeat не продлевает lease дольше `JOB_TIMEOUT_SECONDS` (60 с); дочерний процесс с Pillow в этот момент убивается.
- **Reaper** (в relay, раз в 5 с) возвращает задания с истёкшим lease в `queued` через outbox. Попытка помечается `abandoned`, токен обнуляется.
- **Fencing токеном.** Второй исполнитель может появиться, но опубликовать результат может только владелец текущего токена: COMMIT результата, retry, heartbeat — все с условием `lease_token = мой`. Старая попытка, если оживёт, получит `fenced` и ничего не изменит; её объекты лежат под её токеном, их удалит уборка.
- **Сторона брокера.** AMQP heartbeat 10 с: соединение замороженного клиента закрывается, его неподтверждённые сообщения возвращаются в очередь. `consumer_timeout` 5 мин — для подключённого, но не отвечающего ack.
- Тест: два worker, `docker pause` того, кто держит lease → reaper → второй worker публикует → `unpause` → опубликованный результат не меняется, попытки `[abandoned, succeeded]`.
## Частые уточняющие вопросы
**Почему RabbitMQ, а не Valkey Streams?** Термины README (confirm, ack, prefetch, DLX) — это его родные механизмы; quorum queue пишет на диск до confirm. Брокер отделён от хранилища сессий, отказ одного не задевает другое. Retry, lease и реестр failed всё равно в PostgreSQL, поэтому сложной логики брокера (TTL-очередей) нет.
**Зачем outbox, а не «COMMIT, потом publish в API»?** Между COMMIT и publish процесс может умереть — задание есть, сообщения нет. Outbox пишется в той же транзакции, relay дошлёт. Проверено остановкой брокера и relay.
**Почему staging в отдельном bucket?** У ключей разные права: API может только **писать** в staging и **читать** конечный bucket; worker читает/пишет оба; никто, кроме auditor, не может List. Это проверяет `s3-init` при каждом старте (`api: read staging → refused`, `api: write final → refused`).
**Может ли уборка удалить исходник принятой работы?** Нет, и на трёх уровнях: (1) кандидаты — только `ready` или `failed` старше retention; (2) решение повторяется под блокировкой строки в момент пометки `deleting`, которую берёт и replay; (3) CHECK `attachments_active_has_source` в БД запрещает `queued/processing` без источника. Тесты: retention 0 при `queued` (relay остановлен) — staging цел, а ручной UPDATE отвергнут БД; гонка «уборка прочитала кандидатов → replay → уборка продолжила» воспроизведена паузой `pause_cleanup`.
**Replay = повтор задания?** Нет. `jobctl replay` разрешён только для `failed` с живым источником. Он создаёт **новое** задание `replay_of=<старое>` и пишет оператора и причину в аудит. Для `ready` — отказ `already_ready`, ничего не создаётся.
**Чем постоянная ошибка отличается от временной?** Постоянная не исправится повтором с тем же входом: `invalid_image`, `image_too_large`, `source_missing`, `source_corrupt` → сразу `failed`. Временная — S3/БД недоступны, таймаут, процесс убит → повтор с backoff (full jitter), не более 5 claim-ов, затем `retry_exhausted`.
**Почему 415 в API, а не в worker?** Контракт требует 415 на upload. Преподаватель ловил «202 → failed/invalid_image» в чужих PR. Проверки lab4 (свой PNG-валидатор с проверкой фильтра строк и zlib-потока, `djpeg -strict`) остались синхронными; тесты включают все случаи из рецензий.
+128
View File
@@ -0,0 +1,128 @@
# Pipeline обработки вложений (lab5)
Схема: [migrations/0005_pipeline.sql](../migrations/0005_pipeline.sql). Код: API — [attachments.py](../src/messenger/attachments.py), переходы заданий — [jobs.py](../src/messenger/jobs.py), relay — [relay.py](../src/messenger/relay.py), worker — [worker.py](../src/messenger/worker.py), картинки — [imaging.py](../src/messenger/imaging.py), версии — [pipeline.py](../src/messenger/pipeline.py), оператор — [jobctl.py](../src/messenger/jobctl.py), аудит — [audit.py](../src/messenger/audit.py).
## Кто что делает
```text
клиент ──POST──▶ LB ──▶ API ──(1) INSERT attachments 'pending' ──▶ PostgreSQL
│ (2) PUT оригинал в messenger-staging ──▶ S3 (staging)
│ (3) ОДНА транзакция: 'queued' + jobs + outbox ──▶ PostgreSQL
└─ 202 queued
relay: outbox ─(4) publish + publisher confirm─▶ RabbitMQ (quorum queue) ─(5) deliver─▶ worker
worker: (6) claim: lease + token попытки ─▶ (7) читает источник, сверяет SHA-256 ─▶ (8) варианты
в дочернем процессе ─▶ (9) PUT a/<id>/<token>/* в messenger-attachments ─▶
(10) ОДНА транзакция: варианты + attachment 'ready' (с проверкой токена) ─▶ (11) ack ─▶
(12) staging 'deleting' → S3 DELETE → 'deleted'
```
- **Источник истины — PostgreSQL**: состояние задания, попытки, lease, время следующей попытки (`available_at`), реестр failed, аудит (`job_events`). Брокер только доставляет `job_id`.
- **API не знает брокер** (нет даже сети `queue`). Брокер упал — upload всё равно 202, задания копятся в outbox.
- В сообщении только поля [jobs.schema.json](../contracts/jobs.schema.json): `schema_version, job_id, type, attachment_id, pipeline_version, attempt, created_at`. Никаких байтов, URL, ключей S3, имени файла. Worker берёт `content_type`, размер, SHA-256 и ключ источника из БД.
## Что сохранено в момент 202
1. Полный, **проверенный** оригинал лежит в приватном bucket `messenger-staging`: S3 подтвердил PUT и Content-MD5. Проверки 413/415 делаются до этого, синхронно, теми же валидаторами, что в lab4 (PNG — свой потоковый, JPEG — `djpeg -strict`).
2. Строка `attachments` в статусе `queued`, строка `jobs` (`queued`, attempt 0) и строка `outbox` — **в одной транзакции**, закоммичены (fsync PostgreSQL).
Значит, после 202 можно убить API, relay, broker и worker: работа восстановится из этих двух записей. Честная граница: staging — это уже S3, а не «временная папка». На одном Docker-хосте «устойчиво» значит «переживает рестарт процессов и контейнеров с volumes», а не потерю диска.
## Состояния
Вложение (`attachments.status`):
| Статус | Видно клиенту | Как попадает | Как выходит |
| --- | --- | --- | --- |
| `pending` | нет (404) | INSERT до PUT в staging | → `queued` (COMMIT задания) или удаляется janitor через `PENDING_GRACE_SECONDS` |
| `queued` | да, content 409 | COMMIT задания; retry; истёк lease; replay | → `processing` при claim |
| `processing` | да, content 409 | claim worker | → `ready` / `queued` (retry, lease) / `failed` |
| `ready` | да, варианты | COMMIT результата | никогда не возвращается назад. Reprocess новой версии не меняет статус |
| `failed` | да, `error_code`, content 409 | постоянная ошибка или попытки кончились | → `queued` только через `jobctl replay` |
Задание (`jobs.state`): `queued → processing → succeeded | failed | superseded`, `processing → queued` (retry, lease, graceful stop). `superseded` — старая версия pipeline, когда опубликована более новая.
Ограничения в самой БД (CHECK) не дают коду ошибиться:
- `attachments_active_has_source`: у `queued/processing` есть источник — опубликованный оригинал или staging в состоянии `present`. **Уборка физически не может пометить staging принятой работы**;
- `jobs_lease`: lease есть ровно тогда, когда `processing`;
- `jobs_one_active`: одно активное задание на `(attachment, pipeline_version)`;
- PK `attachment_variants (attachment_id, pipeline_version, name)` — ключ эффекта из контракта.
## Окна отказа (contracts/attachment-states.md)
| Окно | Что остаётся | Кто восстанавливает | Проверка |
| --- | --- | --- | --- |
| после staging, до записи задания | `pending` + объект staging, задания нет, 503 клиенту | janitor API: объект, потом строка (после grace) | `API_FAULT_POINTS=after_s3_put`, test_consistency |
| после COMMIT, до publish | строка outbox без `published_at` | relay при следующем проходе; никто не создаёт задание вручную | broker/relay остановлены, test_pipeline_flow |
| после publish, до записи confirm | сообщение в очереди + неотмеченная строка outbox | relay публикует ещё раз → дубль → no-op | `RELAY_FAULT_POINTS=crash_after_publish` |
| после записи S3, до COMMIT результата | объекты под ключами попытки 1, не опубликованы | lease истекает → reaper → попытка 2 со своими ключами; уборка удаляет ключи попытки 1 | `WORKER_FAULT_POINTS=crash_after_s3_write` |
| после COMMIT результата, до ack | `ready` | redelivery → claim видит `succeeded` → ack без работы | `WORKER_FAULT_POINTS=crash_after_commit` |
| worker умер/завис в processing | lease без продления | reaper (в relay, раз в 5 с) → `queued` + outbox; commit старой попытки отвергается токеном | `crash_after_claim`, `docker pause` |
## Publisher confirm ≠ consumer ack
- **Publisher confirm** (relay ← broker): «брокер принял сообщение и записал его в quorum log». Это граница «намерение передано в очередь»; после неё relay ставит `published_at`.
- **Consumer ack** (worker → broker): «результат работы устойчиво зафиксирован». Worker шлёт ack только **после COMMIT** результата (или после COMMIT решения «retry/failed/no-op»).
- Между ними может пройти сколько угодно времени и случиться любой сбой. Confirm без ack = сообщение ждёт в очереди; потеря ack = повторная доставка.
## Идемпотентность и повторная доставка
Доставка at-least-once: дубль может появиться из relay (crash до отметки), из брокера (нет ack из-за падения worker, разрыв соединения, consumer_timeout), от оператора. Поэтому каждая доставка начинается с `claim` под блокировкой строки `jobs`:
| Состояние задания | Решение | ack |
| --- | --- | --- |
| `succeeded/failed/superseded` | no-op (`noop_finished`) | да |
| `processing` (lease держит другой) | no-op (`noop_leased`), его смерть обработает reaper | да |
| `queued`, `available_at` в будущем | no-op (`noop_not_due`), outbox опубликует вовремя | да |
| `queued`, опубликована версия ≥ своей | `superseded` | да |
| `queued`, пора | claim: attempt+1, новый `lease_token`, строка `job_attempts` с заранее известными ключами | после результата |
Ключ идемпотентности задания — `job_id` (строка в БД), ключ эффекта — `(attachment_id, pipeline_version, variant)`. Объекты пишутся под ключами `a/<attachment>/<token>/<name>`: у каждой попытки свои. Опубликовано ровно то, на что ссылается COMMIT результата. **Fencing**: COMMIT проходит, только если `jobs.lease_token` всё ещё равен токену попытки. Reaper обнуляет токен, поэтому «проснувшаяся» старая попытка ничего не опубликует.
Это не exactly-once **доставка**. Сообщение может прийти несколько раз, а работа выполниться дважды (например, зависший worker досчитает варианты). Exactly-once — только **видимый эффект**: одна опубликованная запись на ключ эффекта, монотонная версия, мусор попыток убирается.
## Зависший vs долго работающий worker
- Долго работающий продлевает lease каждые `JOB_LEASE_SECONDS/3` (heartbeat в БД, `WHERE lease_token = мой`).
- Зависший (`docker pause`, deadlock, потеря сети к БД) не продлевает; через `JOB_LEASE_SECONDS` reaper возвращает задание.
- Worker, у которого жив heartbeat, но зависла обработка, ограничен `JOB_TIMEOUT_SECONDS`: дочерний процесс убивается, heartbeat перестаёт продлевать lease после этого срока.
- Если heartbeat узнал, что lease потерян, попытка отменяется сама. Даже если не отменилась — её COMMIT отвергнет fencing.
- Брокер со своей стороны: AMQP heartbeat 10 с закрывает соединение замороженного клиента и возвращает его неподтверждённые сообщения; `consumer_timeout` 5 мин — для подключённого, но не отвечающего ack.
## Retry, failed, replay
- `JOB_MAX_ATTEMPTS=5` claim-ов на задание. Backoff — full jitter: `uniform(0, min(JOB_RETRY_MAX_SECONDS, JOB_RETRY_BASE_SECONDS·2^(n−1)))`. Задержка хранится в `jobs.available_at` и строке outbox — повтор проходит тем же путём outbox → broker, без TTL-очередей.
- Постоянные ошибки (сразу `failed`): `invalid_image`, `image_too_large`, `source_missing`, `source_corrupt`. Временные: `storage_unavailable`, `processing_timeout`, `processing_killed`, `processing_failed`. Когда попытки кончились — `retry_exhausted`.
- Реестр failed — view `failed_jobs` (`jobctl list-failed`). DLQ RabbitMQ (`messenger.attachment-jobs.dlq`) — для «ядовитых» сообщений: не по схеме или превысили `x-delivery-limit=20`.
- Страховка от потерянного сообщения: `queued`-задание без claim и без публикаций дольше `QUEUED_REPUBLISH_SECONDS` получает новую строку outbox.
- `jobctl replay <id>`: только для `failed` с живым источником, создаёт **новое** задание `kind=replay, replay_of=<failed>`, пишет оператора и причину в `job_events`. Для `ready` — отказ `already_ready`, ничего не создаётся.
## Уборка (worker), всегда под блокировкой строки
- staging `ready` — сразу после COMMIT результата; staging `failed` — через `STAGING_RETENTION_SECONDS`. Порядок: под `UPDATE … WHERE <условие заново>` пометить `deleting` → S3 DELETE → `deleted`. Replay берёт ту же блокировку: либо replay первым (строка уже `queued`, уборка её пропустит), либо уборка первой (replay видит `deleting` и отказывает `source_missing`).
- Объекты попыток, которые не опубликовали результат (`retry/failed/abandoned/superseded`): удаляются по `planned_keys` через `ORPHAN_GRACE_SECONDS`. Перед этим проверяется, что токен не текущий и ни один ключ не опубликован. Новые результаты (replay, другая попытка) лежат под другими ключами — устаревший проход не может их удалить.
- `pending` без задания — janitor API (как в lab4).
- Опубликованные варианты старых версий pipeline сохраняются (ограничение, см. REPORT).
## Версии pipeline (трек 2)
Версия фиксируется в задании при создании (`PIPELINE_VERSION` для upload, `jobctl reprocess --pipeline N` для готового вложения). Версии 1/2/3 отличаются параметрами кодеков, геометрия — по контракту. Публикация: только если `N > published_version`; иначе `superseded`. Reprocess неготового вложения запрещён: его единственный источник — staging текущего задания.
## Лимиты worker
| Что | Чем |
| --- | --- |
| параллельность | prefetch = `WORKER_CONCURRENCY` (2) + семафор на дочерние процессы |
| bytes | размер из БД ≤ `MAX_UPLOAD_BYTES` проверяется до скачивания; длина и SHA-256 скачанного = БД |
| пиксели | `width×height` из заголовка ≤ `MAX_IMAGE_PIXELS` до декодирования; JPEG декодируется с DCT-масштабом (`draft`) |
| память | `RLIMIT_AS = IMAGE_MAX_MEMORY_MB` (768) у дочернего процесса; контейнер 1536m без swap |
| время | `JOB_TIMEOUT_SECONDS` (60): дочерний процесс убивается, lease перестаёт продлеваться |
## Варианты
| Вариант | Формат | Геометрия | Параметры v1 |
| --- | --- | --- | --- |
| thumbnail | JPEG baseline 4:2:0 | вписан в 256×256, без увеличения, округление вниз, ≥1 px | q=85, optimize |
| crop | JPEG | центральный квадрат → 128×128 (маленькие увеличиваются) | q=85 |
| optimized | WebP lossy | вписан в 1280×1280, без увеличения, alpha сохраняется | q=80, method=4 |
EXIF orientation применяется к пикселям; в варианты не копируются EXIF, XMP, ICC, комментарии. Пиксели считаются sRGB. Alpha при ресайзе — premultiplied (без цветных ореолов), для JPEG композится на белый. 16-битный серый масштабируется (`/257`), а не обрезается. Оригинал публикуется побайтно без изменений. Уменьшение размера маленьких файлов не обещается.
+114
View File
@@ -0,0 +1,114 @@
# Запуск на ноутбуке с Windows и сценарий защиты ЛР 5
Команды — в **PowerShell** из папки проекта (где лежит `compose.yaml`). Переменные `$env:...` действуют до закрытия окна.
## 1. Что установить один раз
| Программа | Зачем | Важно |
| --- | --- | --- |
| [Git for Windows](https://git-scm.com/download/win) | clone и Git Bash | путь по умолчанию `C:\Program Files\Git`: оттуда `scripts\*.cmd` запускают `.sh`-хуки |
| [Docker Desktop](https://www.docker.com/products/docker-desktop/) | PostgreSQL, Valkey, SeaweedFS (S3), RabbitMQ, HAProxy, API, relay, worker | backend WSL 2; в Settings → Resources ≥ 4 CPU и ≥ 8 ГБ RAM (сумма лимитов контейнеров ~6,5 ГБ) |
| [Python 3.12+](https://www.python.org/downloads/windows/) | secrets, публичные и свои тесты, сценарии | галочка **Add python.exe to PATH** |
| GNU make (необязательно) | `make check/test/...` | `winget install ezwinports.make`, затем **новое** окно; в каждом окне `$env:Path += ";C:\Program Files\Git\usr\bin"` (рецептам нужен `sh`) |
## 2. Развернуть проект (заранее, нужен интернет)
```powershell
git clone https://gitea.privcloud.tech/wfa/mtusi2026lab5 mtusi2026lab5
cd mtusi2026lab5
git checkout solution/bvt2302-bodanyuk
python scripts\init_secrets.py # пароли БД/Valkey, 4 пары ключей S3, пользователи RabbitMQ -> .\secrets
Copy-Item .env.example .env
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
```
Первый запуск качает образы (~1,2 ГБ) и собирает образ приложения — 3–10 минут. Команда завершается, когда postgres, valkey, s3, broker, обе реплики api, lb, relay и worker в `healthy`, а `migrate` и `s3-init` вышли с кодом 0. Проверки прав S3: `docker compose logs s3-init`.
Окружение для своих тестов (один раз):
```powershell
python -m venv .venv
.venv\Scripts\python -m pip install --require-hashes --no-deps -r requirements.txt
.venv\Scripts\python -m pip install -r requirements-test.txt -r requirements-dev.txt
```
Стенды ЛР 3/4 занимают порт 8080 — остановить: `docker compose -p mtusi-lab4 stop` (данные сохранятся).
## 3. Перед защитой
```powershell
$env:PYTHONUTF8 = "1"; $env:Path += ";C:\Program Files\Git\usr\bin"
docker compose up -d --wait
make check test PYTHON=python # 202 -> ready, настоящий JPEG 256x160
make jobs # задания по состояниям, хвост outbox
```
## 4. Сценарий защиты README — по шагам
**Шаг 1. `make test`**: API возвращает 202, GET доходит до ready, оригинал и настоящий JPEG thumbnail проверяются (см. раздел 3).
**Шаги 2–3. Worker остановлен → 202 → content 409 → рестарт API и брокера с volumes → worker → ready.** Скрипт печатает каждый шаг, ID вложения и сообщения, код ответа; токены не печатает:
```powershell
.venv\Scripts\python scripts\demo_pipeline.py
```
Что он делает:
1. `docker compose stop worker`;
2. upload → **202 queued**; `GET /content` и `?variant=thumbnail` → **409**; обычное сообщение → 201; сообщение с этим вложением → 201;
3. показывает строку outbox (`published_at` заполнен — relay получил confirm) и глубину очереди `messenger.attachment-jobs` (1);
4. `docker compose restart api broker` (volumes не трогаются), ждёт готовности; очередь снова показывает 1, вложение по-прежнему `queued`;
5. `docker compose start worker` → **ready**, скачивает thumbnail (JPEG 256×160), сверяет SHA-256 и размеры;
6. печатает журнал задания (`jobctl show`): `created → claimed → succeeded`, одна попытка.
То же автоматически: `.venv\Scripts\python -m pytest student-tests\test_pipeline_flow.py -k worker_stopped -v`.
**Шаг 4. Уровень 4 вживую.**
```powershell
# crash после записи в S3 до ack/COMMIT; разрыв COMMIT/publish; publish/confirm:
.venv\Scripts\python -m pytest student-tests\test_pipeline_flow.py -k "crash or broker_down or relay" -v
# retry с backoff, retry_exhausted -> реестр failed -> replay; replay готового -> отказ:
.venv\Scripts\python -m pytest student-tests\test_pipeline_flow.py -k "retry or permanent" -v
make failed # реестр failed
docker compose run --rm --no-deps jobctl replay <attachment_id> --operator alice --reason "причина устранена"
docker compose run --rm --no-deps jobctl show <attachment_id> # задания, попытки, аудит
# зависший worker (docker pause) теряет lease, второй worker публикует, первый не может:
.venv\Scripts\python -m pytest student-tests\test_pipeline_flow.py -k hung -v -s
```
**Трек 2 вживую.**
```powershell
make audit # инварианты I1-I7 по всей БД и обоим bucket (read-only)
.venv\Scripts\python bench\pipeline_faults.py --output evidence\track2-demo --uploads 3 # ~15 мин
```
Готовые результаты: [evidence/track2/summary.txt](../evidence/track2/summary.txt).
**Публичные проверки сохранности и failover.**
```powershell
make test-persistence ACTION_SCRIPT=scripts/restart.cmd PYTHON=python # restart всего стенда с volumes
make test-failover ACTION_SCRIPT=scripts/stop-one.cmd PYTHON=python
make restore PYTHON=python
```
**Все свои тесты** (~40 мин): `.venv\Scripts\python -m pytest student-tests -v`.
## 5. Если что-то пошло не так
| Симптом | Что сделать |
| --- | --- |
| `error during connect … dockerDesktopLinuxEngine` | Docker Desktop не запущен — запустить и подождать минуту |
| `port is already allocated` на 8080/8404 | стенд lab3/lab4 (`docker compose -p mtusi-lab4 stop`) или в `.env` `APP_PUBLISH_PORT=8081`, `LB_STATS_PORT=8405` |
| `secrets/... not found` | не выполнен `python scripts\init_secrets.py` |
| `s3-init` exit 1 | `docker compose logs s3-init`: какая проверка доступа не прошла |
| broker долго `starting` | первый старт RabbitMQ ~20 с; `docker compose logs broker` |
| вложение висит в `queued` | `make jobs`: если `outbox_due > 0` — смотреть `docker compose logs relay`; если очередь не пуста — `docker compose logs worker` |
| `UnicodeDecodeError` в `tests\*.py` | не задан `$env:PYTHONUTF8 = "1"` |
| локальный `.env` устарел | сравнить с `.env.example`: значения `.env` перекрывают умолчания compose |
| начать с чистого листа | `docker compose down -v` (удаляет учебные данные: БД, bucket, очередь) → `up -d --build --wait` |
Остановить после защиты: `docker compose down` (данные сохранятся).