From cf6e92957cae8dcc73ed8e7403a594a0dfc06bc9 Mon Sep 17 00:00:00 2001 From: Alexey Bodanyuk <144894236+wfa22@users.noreply.github.com> Date: Sat, 31 Oct 2026 17:17:17 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20PIPELINE,=20DEFENSE,=20DATA=5FMODEL,=20?= =?UTF-8?q?WINDOWS=20=D0=B4=D0=BB=D1=8F=20lab5;=20=D1=87=D0=B5=D1=80=D0=BD?= =?UTF-8?q?=D0=BE=D0=B2=D0=B8=D0=BA=20REPORT?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 --- REPORT.md | 149 +++++++++++++++++++++++++++++++++++++++------ docs/DATA_MODEL.md | 57 +++++++++++++++++ docs/DEFENSE.md | 48 +++++++++++++++ docs/PIPELINE.md | 128 ++++++++++++++++++++++++++++++++++++++ docs/WINDOWS.md | 114 ++++++++++++++++++++++++++++++++++ 5 files changed, 479 insertions(+), 17 deletions(-) create mode 100644 docs/DATA_MODEL.md create mode 100644 docs/DEFENSE.md create mode 100644 docs/PIPELINE.md create mode 100644 docs/WINDOWS.md diff --git a/REPORT.md b/REPORT.md index e98f75e..370bdad 100644 --- a/REPORT.md +++ b/REPORT.md @@ -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 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. diff --git a/docs/DATA_MODEL.md b/docs/DATA_MODEL.md new file mode 100644 index 0000000..59dae32 --- /dev/null +++ b/docs/DATA_MODEL.md @@ -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///original`, у строк lab4 — `o/`). `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:`, значение `{user_id, expires_at}`. Срок жизни задаётся абсолютным `PXAT expires_at`, поэтому рестарт его не продлевает. Включён `appendonly yes` + `appendfsync always`: подтверждённые вход и logout сохраняются до ответа клиенту. Valkey — **единственное** хранилище сессий, это не кэш над PostgreSQL. Поэтому нет второй копии, которая могла бы «оживить» отозванный токен после отказа. Если Valkey недоступен, проверить сессию нельзя: защищённые запросы и logout получают 503, анонимный доступ не открывается. +- `SESSION_STORE=postgres`: таблица `sessions`, проверка `expires_at > now()` в запросе. diff --git a/docs/DEFENSE.md b/docs/DEFENSE.md new file mode 100644 index 0000000..6b6cb3b --- /dev/null +++ b/docs/DEFENSE.md @@ -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///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`) остались синхронными; тесты включают все случаи из рецензий. diff --git a/docs/PIPELINE.md b/docs/PIPELINE.md new file mode 100644 index 0000000..fe6c192 --- /dev/null +++ b/docs/PIPELINE.md @@ -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///* в 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///`: у каждой попытки свои. Опубликовано ровно то, на что ссылается 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 `: только для `failed` с живым источником, создаёт **новое** задание `kind=replay, replay_of=`, пишет оператора и причину в `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`), а не обрезается. Оригинал публикуется побайтно без изменений. Уменьшение размера маленьких файлов не обещается. diff --git a/docs/WINDOWS.md b/docs/WINDOWS.md new file mode 100644 index 0000000..e5236a8 --- /dev/null +++ b/docs/WINDOWS.md @@ -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 --operator alice --reason "причина устранена" +docker compose run --rm --no-deps jobctl show # задания, попытки, аудит +# зависший 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` (данные сохранятся).