Files
mtusi2026lab5/REPORT.md
T

213 lines
32 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Лабораторная 5 — очереди и обработка изображений
**Горбанюк, БВТ2301. Целевая оценка: 5, трек 2 — идемпотентность versioned pipeline с внедрением отказов.**
Решение опубликовано в публичном форке исходного проекта; МР преподавателю открыт. Ветка `solution/bvt2301-gorbanyuk`, проверенная версия — тег `lab5-verified`. Название МР: **«ЛР 5 — БВТ2301 — Горбанюк — на 5»**. README задания, COURSE, CONTRIBUTING, контракты и публичные тесты сохранены.
Публичный форк: <https://gitea.privcloud.tech/Wemiliam/mtusi2026lab5>. Ветка решения: `solution/bvt2301-gorbanyuk`, целевая ветка преподавателя — `main`. Ветка опубликована; МР преподавателю: <https://gitea.privcloud.tech/mtusi2026/mtusi2026lab5/pulls/10>.
## Запуск из самостоятельного clone
Нужны Git, Docker с Compose v2+, Python **3.14.7**, `uv 0.12.13`, доступ к реестрам и официальным Go-модулям при первом build. Проверено на ARM64, Docker 29.8.1 / Compose 5.5.1; Docker VM: 18 CPU, 7.75 GiB RAM. Выделите Docker около 6 GiB RAM и несколько GiB диска. Соседние лабораторные не нужны.
Команды выполняются из корня клонированного репозитория.
```sh
uv sync --locked
make bootstrap
VCS_REF=$(git rev-parse HEAD) make up
make check validate PYTHON=.venv/bin/python
make test PYTHON=.venv/bin/python
```
API: `http://127.0.0.1:8085`, две реплики за HAProxy. У API нет собственных опубликованных портов. `bootstrap` создаёт случайные локальные секреты в игнорируемом `secrets/` и `.env`, сохраняя прежние значения. Каталог 0700; файлы читаются контейнерным UID через Compose secrets. Это локальные файлы, не централизованное зашифрованное хранилище секретов.
Одноразовый `migrate` применяет SQL под advisory lock, проверяя checksum ранее применённых миграций. `bucket-init` создаёт private buckets и IAM identities. API ждёт их успешного завершения. MinIO и mc собираются из официальных исходников, закреплённых на `RELEASE.2025-10-15T17-29-55Z` / `RELEASE.2025-08-13T08-35-41Z`, Go 1.26.7. Первый холодный build может занять несколько минут. Бинарник имеет label `DEVELOPMENT.GOGET`; фактическая версия исходников проверяется через Go build info, а не этот label. Это учебный pin, без заявления о текущей production-поддержке.
Для собственных интеграционных проверок включите локальные test ports и отдельный тестовый bucket:
```sh
docker compose --env-file .env -f compose.yaml -f compose.test.yaml up -d --build --wait
make lint unit
uv run python scripts/verify_pipeline.py --output /tmp/pipeline-new.json
uv run python scripts/verify_cluster.py --output /tmp/cluster-new.json
```
Override открывает **только loopback**: PG 55437, кэш 56384, брокер 56385, S3 59005. Он включает операторские single-use fault hooks и timeout job **5 s / lease 8 s**. Обычный Compose оставляет hooks выключенными, timeout **20 s / lease 23 s**. Не запускайте одновременно сценарии, меняющие состояние одного стенда. Выходной файл должен быть новым, предыдущие доказательства не перезаписываются.
Реальная проверка возраста и очистки:
```sh
uv run python scripts/verify_cleanup.py seed --seed /tmp/gc-seed-new.json
# Пока объекты стареют, выполните другие проверки.
uv run python scripts/verify_cleanup.py verify --seed /tmp/gc-seed-new.json --output /tmp/gc-new.json
```
Второй вызов дожидается >=301 s после terminal failed. Возраст S3 и часы не подменяются. Seed содержит только ID, без credentials. Скрипт проверяет orphan, failed retention, защиту active и опубликованных объектов; после проверки отложенная работа освобождается и доходит до ready. Быстрый unit-тест гонки с API моделирует возраст метаданных отдельно, не заменяя эту проверку.
```sh
make down # Остановить, сохранив данные.
docker compose --env-file .env up -d --wait # Возобновить.
# Только намеренное удаление ВСЕХ учебных данных этого проекта:
docker compose --env-file .env down --volumes
```
Проект `mtusi-lab5` имеет собственные `postgres_data`, `s3_data`, `broker_data`. Кэш одноразовый: сессии хранятся в PostgreSQL. Секреты/volumes не входят в Git или bundle.
## Архитектура и транзакционные границы
```mermaid
flowchart LR
C[Клиент] --> LB[HAProxy]
LB --> A1[API 1]
LB --> A2[API 2]
A1 --> PG[(PostgreSQL)]
A2 --> PG
A1 --> S[(Приватный S3)]
A2 --> S
PG --> R[Outbox relay и watchdog]
R --> B[(Valkey Streams AOF)]
B --> W[Worker supervisor]
W --> P[Ограниченные дочерние процессы]
P --> S
P --> PG
```
Перенесены собственные FastAPI API, Argon2id, серверные Bearer-сессии, keyset pagination, членство в чате, PostgreSQL, кэш, две реплики и атомарная идемпотентность сообщений. Из ЛР4 сохранены приватность, ограничения файлов, оригинальные байты и связь с чатом. Объявленный переход: **201 ready → 202 queued**; queued/processing можно прикреплять к сообщению, failed нельзя.
БД — источник истины о состоянии, S3 — о байтах. Брокер — **отдельный от кэша** Valkey 8.1.3: persistent volume, AOF `appendfsync always`, RDB `60 1`, максимум 192 MiB данных, `noeviction`. Кэш — другой процесс без persistence, `allkeys-lru`. Переполнение/остановка брокера задерживает relay; PG outbox остаётся сохранённым.
1. API проверяет сессию/чат, имя, MIME, фактический поток <=10 MiB, время приёма <=15 s, целостность PNG/JPEG, <=40 млн пикселей. Pixel guard действует **до** полной распаковки. На API один upload slot, ожидание <=5 s, затем 429. Временный файл в tmpfs не является durable staging.
2. БД создаёт upload reservation с lease 120 s. Проверенный оригинал записывается в persistent private S3 `staging/<UUID>`. Имя клиента не используется как ключ. PUT имеет ограниченные socket timeouts без автоматических повторов.
3. **Одна PG-транзакция** блокирует/проверяет reservation, создаёт attachment=queued, job и outbox, отмечает handoff. После COMMIT API возвращает **202 со снимком queued**. Thumbnail ещё не обещан; worker может успеть завершить до первого GET.
4. Relay выбирает due outbox через `FOR UPDATE SKIP LOCKED`, делает XADD, затем фиксирует published_at. Потеря ответа XADD/COMMIT вызывает повтор с тем же job_id. До шага 3 возможен непринятый orphan: общей транзакции S3+PG нет. Reservation и retention GC закрывают это окно без ложного 202.
5. Worker получает COUNT=1 из consumer group. В короткой PG-транзакции захватывает job, увеличивает attempt, сохраняет fence/lease. Pillow работает вне SQL-транзакции, в **отдельном OS-процессе**. Supervisor держит не более двух child, убивает зависший по wall clock. Child RLIMIT_AS 768 MiB; worker container 1536 MiB / 2 CPU / tmpfs 64 MiB / pids 96.
6. Worker сверяет исходный размер/SHA-256, повторно валидирует изображение, сохраняет original и три варианта в `objects/<attachment>/v<version>/<variant>`. После всех PUT атомарно публикует метаданные **при совпадении текущей версии, fence и действующего lease**.
7. XACK означает устойчивый эффект. XACK+XDEL атомарны в Lua для единственной consumer group; pending не обрезаются через MAXLEN. XAUTOCLAIM восстанавливает неподтверждённые записи. При временной ошибке ACK выполняется после durable retry-intent, при failed — после terminal registry.
API readiness проверяет БД/миграции и S3; кэш, broker, relay и worker не входят в обязательный синхронный путь. При остановленном worker API способен устойчиво принять файл, но обработка задержится. Liveness проверяет только процесс. `DATABASE_URL_FILE`, `CACHE_URL_FILE`, `BROKER_URL_FILE`, S3 file credentials соответствуют `.env.example`; pool size=8, upload=10 MiB/40M px, concurrency=2, max attempts=5, staging retention=86400 s. Secret-поля Settings исключены из repr.
## Состояния, retry, версии и идемпотентность
`queued → processing → ready`; временная ошибка/истёкший lease возвращают queued с due time. Постоянная ошибка или пять неудач дают failed с безопасным error_code. **Attempt — управляемая попытка обработки, не число доставок брокера.** Envelope строго соответствует `contracts/jobs.schema.json`: schema_version/type/job_id/attachment_id/pipeline_version/attempt/created_at; trace context зарезервирован схемой. Bytes, credentials, filename, URL в stream не передаются. Недоверенный envelope проверяется; неверный помещается в служебный DLQ без копирования произвольных полей.
`attachment_jobs WHERE state='failed'` — durable failed registry. Audit фиксирует claim, публикации, отказы, replay, старые доставки, fence. Temporary storage/network ошибки повторяются; повреждение/неверный формат/пиксели/MemoryError постоянны. Supervisor timeout восстанавливает watchdog relay. Full jitter: равномерно от **0.25 s до min(30, 2^attempt)**, абсолютное время due сохраняется в БД. После пятой неудачи автоматических повторов нет.
```sh
docker compose --env-file .env exec worker python -m messenger.operator failed
docker compose --env-file .env exec worker python -m messenger.operator replay <attachment-uuid>
docker compose --env-file .env exec worker python -m messenger.operator new-version <attachment-uuid>
docker compose --env-file .env run --rm reconciler
docker compose --env-file .env run --rm reconciler python -m messenger.cleanup --apply
```
CLI доступен только оператору локального стенда, не публичному HTTP клиенту. Replay разрешён только для failed с retained source: CLI проверяет наличие объекта, сохраняет job_id/версию, начинает новый ограниченный цикл попыток с audit. Ready replay отклоняется. New-version реализует **v1→v2**: optimized WebP quality 82→76; другие преобразования одинаковы. Source key фиксирован в job; для reprocess готового attachment берётся опубликованный original.
Ключ эффекта **(attachment_id, pipeline_version, variant)**. UNIQUE(attachment_id,pipeline_version) защищает logical job. Имена объектов детерминированы; повторные PUT занимают те же ключи, без второго набора вариантов. Старый процесс может дописать свой prefix v1, но не v2. PG fence/lease дополнительно запрещают устаревший COMMIT. Ready-дубль сверяет полноту и HEAD size/checksum, затем ACK без resize. Старые version/attempt не захватывают новую работу. **Менять алгоритм, сохраняя номер версии, нельзя:** это нарушит детерминированность.
## Изображения, приватность и очистка
| Вариант | Параметры |
| --- | --- |
| original | Побайтная копия, тот же MIME/размер/SHA-256, включая исходные EXIF |
| thumbnail | JPEG quality 85/subsampling 0, LANCZOS, <=256×256, без увеличения |
| crop | JPEG quality 85/subsampling 0, центральный квадрат 128×128, увеличение маленьких допустимо |
| optimized | WebP quality 82(v1)/76(v2), method 4, <=1280×1280 без увеличения |
EXIF orientation применяется до преобразований; alpha компонуется на белый. Размеры вписывания округляются вниз, минимум 1 px: 320×200 → 256×160. Generated variants не содержат EXIF. WebP не обязан быть меньше каждого маленького исходника.
Metadata и каждый download требуют сессию/членство; чужое — 404, content queued/processing/failed — 409. Download идёт через API, без redirect, со своим MIME/размером, private/no-store/nosniff. Storage keys отсутствуют в публичных метаданных. S3 anonymous GET — 403. IAM разделён: API пишет staging/читает final; worker читает оба prefix/пишет final; cleanup читает/удаляет, не пишет; тестовая identity ограничена отдельным bucket. Root keys не доступны API/worker.
Cleanup по умолчанию dry-run, применение явное. Retention **86400 s**, hard minimum 300 s. Удаляются старые непринятые orphan, staging после опубликованного результата, остатки старых версий. Active queued/processing защищает объекты attachment. Текущие published originals/variants сохраняются даже без message-link. Failed source сохраняется >=retention после отказа, затем удаляется с source_expired/audit; replay потерянного источника не обещается.
Перед DELETE повторяется HEAD ETag/size/age; недоступность не считается 404. Коллекторы сериализованы advisory lock. Replay/new-version и GC согласуются row lock attachment; reservation защищает ещё не завершённый handoff API: expired/abandoned upload не сможет после удаления вернуть 202.
## Доказательства критериев
| Критерий | Команда/сценарий | Наблюдение и файл |
| --- | --- | --- |
| Контракт и исходные tests | `make check validate`, Git compare | PASS, неизменённый skeleton; `evidence/contract.txt`, `audit.json` |
| 202, реальный thumbnail, сессии, ACL | `make test` | PASS; `evidence/smoke.txt` |
| API, гонки, размеры/EXIF/alpha, replay, GC fence | `make unit` | 84 проверки; `evidence/unit.txt` |
| Worker down → queued message → API restart → broker SIGKILL → ready | Первый сценарий `verify_pipeline.py` | Реальные CID/StartedAt, сохранённые Stream IDs; `evidence/pipeline.json` |
| COMMIT/publish gap, publish до outbox COMMIT | Первые два сценария матрицы | Восстановление без ручной новой job; `pipeline.json` |
| Crash до/после S3 и после result COMMIT до ACK | Три сценария worker | Attempts 2/2/1, один набор результатов; `pipeline.json` |
| Transient/permanent, jitter, timeout, exhaustion, replay | Четыре сценария матрицы | Safe failed, lease recovery, audited CLI replay; `pipeline.json` |
| Bounded concurrency/time/RAM, варианты | Supervisor + checksum/decode/cgroup | Три реальных варианта; `pipeline.json` |
| Versioned pipeline, reorder, stale writer | v2 перед v1; 44 доставки и publication fence | Новая версия/байты не перезаписаны; `pipeline.json` |
| Private S3, чтение другой API | Anonymous/IAM отрицательные checks; actual uploader stopped | 403 и download с другой реплики; `pipeline.json` |
| Retention/cleanup | `verify_cleanup.py`, реальный возраст >=301 s | Active/ready сохранены, expired/orphan удалены; `cleanup.json` |
| Failover/rolling/persistence | `verify_cluster.py`, публичные resilience hooks | Настоящие процессы/stores; `cluster.json`, `failover.txt`, `persistence.txt` |
| Чистый clone | Новые secrets/volumes и отдельный Compose project | `clean-clone.json`, `clean-clone.txt` |
### Исследование трека 2
Гипотеза: at-least-once + детерминированные versioned keys + PG fence сохраняют подтверждённые работы и запрещают старому writer опубликоваться поверх нового. `verify_pipeline.py` воспроизводит 10 сценариев на настоящих PG/S3/Stream/processes. Hooks одноразовые, операторские, выключены в обычном Compose. Crash — `os._exit(87)` worker child/relay; hang убивает supervisor. After_effect расположен после PUT original, до полного результата; after_commit — после всех вариантов/COMMIT до ACK.
Raw JSON содержит время, attempts, audit/PID, object count, версии, CID/StartedAt, cgroup memory/CPU. Длительности включают остановки/ожидание redelivery, **не являются p95 обычного upload**. `memory.peak` — пик всей cgroup с дочерними процессами, не RSS одного процесса. Реальные варианты декодируются и проверяются по SHA-256. Инварианты проверяются assertions. Матрица перегрузки/concurrency не заявляется: выбран трек 2.
### Измеренные результаты локального прогона
| Сценарий | Время, s | Attempts последнего цикла |
| --- | ---: | ---: |
| commit_publish_gap_api_restart_broker_sigkill | 12.72 | 1 |
| publish_before_outbox_commit_duplicate | 14.33 | 1 |
| worker_crash_before_effect | 13.89 | 2 |
| worker_crash_after_effect | 13.86 | 2 |
| worker_crash_after_commit | 11.78 | 1 |
| transient_2 | 8.71 | 3 |
| hang_1 | 13.66 | 2 |
| permanent_1_failed_then_explicit_replay | 6.04 | 1 |
| transient_5_failed_then_explicit_replay | 30.80 | 1 |
| reorder_stale_v1_after_v2_and_publication_fence | 19.35 | 1 |
Матрица: 11 подтверждённых upload, потеряно 0, устаревших перезаписей 0; по 4 объекта текущей версии. У failed перед replay отдельно зафиксированы исходные attempts 1/5; число в таблице для них относится к успешному новому циклу. Пик worker cgroup 209.18 MiB; OOM kills=0. Измерение относится к небольшому fixture 320×200 и этому прогону.
Реальный GC: failed age 301.00 s; dry-run нашёл 14 кандидатов и ничего не удалил; apply удалил 14. Активный staging сохранён и затем обработан; 4 текущих published objects остались неизменными. Эти counts зависят от числа прошлых синтетических загрузок, критерии проверяются по конкретным seed ID.
Отказы API под шестью потоками: реплика 1: 201 подтверждённых записей, первое успешное чтение/запись после начала действия через 1.91 s, ошибки 2.92%; реплика 2: 165 подтверждённых записей, первое успешное чтение/запись после начала действия через 1.86 s, ошибки 6.37%. Rolling replacement: 563 подтверждённых записей, все сохранены, ошибки 5.13%. Не обещается отсутствие транзиентных 5xx во время отказа; сообщения повторяются тем же Idempotency-Key. Публичный failover отдельно: 130 успешных записей, 2 неудачные попытки, первое восстановление 0.984 s. Persistence перезапустил реальные API/PG/S3/broker/cache/worker/relay/LB и сохранил действительную сессию. Эти показатели относятся к локальной синтетической проверке отказов, не к оценке пропускной способности очереди.
## Ответы на вопросы README
**Publisher confirm и consumer ack.** Confirm подтверждает приём от producer брокером; он не говорит, что worker сделал картинку. ACK подтверждает устойчивую обработку либо сохранённое решение о retry/failed. В RabbitMQ это разные механизмы. Здесь publisher boundary — ответ XADD при AOF appendfsync always; consumer boundary — XACK. Неопределённый исход publish приводит к повторной отправке; смерть после result COMMIT до XACK — к повторной доставке.
**Что сохранено при 202?** Все байты уже приняты и проверены, original находится в persistent staging, PG COMMIT содержит queued attachment, logical job и outbox-intent. Thumbnail ещё не обещан. Брокер может быть недоступен: relay отправит позже. Локальная память/tmpfile не входят в гарантию. До 202 неоднозначный отказ может оставить orphan; повтор upload создаёт новый ID, поскольку идемпотентность upload контрактом не задана.
**Почему нормальны повторы; где ключ?** Нельзя атомарно объединить PG COMMIT, S3 PUT и ACK разных систем. Всегда есть окно «эффект выполнен, подтверждение потеряно». Job_id стабилен при redelivery, UNIQUE защищает logical job, (attachment_id,pipeline_version,variant) — эффект, fence — право публикации. Это **не exactly-once delivery**: доставок/PUT может быть несколько; один текущий набор метаданных — свойство нашего идемпотентного эффекта в заявленной модели.
**Как отличить зависший worker от долгого?** По одному молчанию достоверно невозможно. Мы задаём бюджет и lease: до истечения захват действителен, после разрешено восстановление. Supervisor убивает child по timeout; relay после более длинного lease создаёт bounded retry. Легитимная долгая обработка тоже может быть прервана — цена конечного бюджета. Новая попытка получает новый fence; старая не может COMMIT. Количество процессов/prefetch ограничено; XAUTOCLAIM восстанавливает доставку, а PG lease определяет право на эффект.
Подходы: разделение HTTP/domain/storage; явные транзакции; transactional outbox; at-least-once consumer group; идемпотентный consumer; конечный автомат; fencing/leases; bounded retry/backoff/jitter; failed registry; versioned namespace; least privilege; fault injection и проверяемые инварианты. Очередь сама по себе этих свойств не даёт.
## Ограничения
Один host/PG/S3/broker не переживут потерю всех дисков/VM. Backup, репликация stores и удалённый TLS не реализованы. HTTP — только loopback/синтетические данные. Остановка relay задерживает также lease recovery, сохраняя задания. Оператор наблюдает failed/backlog/disk и запускает cleanup; scheduler не добавлен. Восстановление утраченных published objects из backup не реализовано. Audit/jobs не архивируются автоматически. PG/S3 место конечно; admission по размеру backlog не исследовался.
Тесты — воспроизводимая проверка перечисленных окон, а не математическое доказательство всех interleavings. Проверены два worker slots и версии 1/2; большие картинки под максимальной конкуренцией отдельно не исследованы. Конечные RAM/time лимиты могут отклонить легитимный большой файл; OOM/timeout восстанавливаются по lease с конечным бюджетом попыток. SHA-256 проверяет целостность, не авторство. Новая версия алгоритма требует реализации/тестирования, не только изменения числа.
## Источники и библиотеки
Python 3.14.7; FastAPI 0.143.3/Pydantic 2.14.1/Uvicorn 0.54.0; psycopg 3.3.6, PostgreSQL 18.3; redis client 8.1.0, Valkey 8.1.3; boto3 1.43.109, Pillow 13.0.0; HAProxy 3.2.1. Python-зависимости закреплены `uv.lock`, images/source pins — Compose/Dockerfile/infra.
- Нормативные README, contracts/README.md, attachment-states.md, jobs.schema.json этого skeleton.
- [Valkey XREADGROUP](https://valkey.io/commands/xreadgroup/), [XAUTOCLAIM](https://valkey.io/commands/xautoclaim/), [XACK](https://valkey.io/commands/xack/), [persistence](https://valkey.io/topics/persistence/).
- [RabbitMQ reliability](https://www.rabbitmq.com/docs/reliability), [confirms/acknowledgements](https://www.rabbitmq.com/docs/confirms) — теория границ, RabbitMQ в стенде не используется.
- [PostgreSQL row locks](https://www.postgresql.org/docs/18/explicit-locking.html), [SKIP LOCKED](https://www.postgresql.org/docs/18/sql-select.html).
- [Pillow ImageOps](https://pillow.readthedocs.io/en/stable/reference/ImageOps.html), [file formats](https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html).
- [MinIO source pin](https://github.com/minio/minio/tree/RELEASE.2025-10-15T17-29-55Z), [mc source pin](https://github.com/minio/mc/tree/RELEASE.2025-08-13T08-35-41Z).
Заявленные результаты получены запуском сохранённых проверок; ограничения и операторские вмешательства описаны выше.
## Финальная проверка самостоятельности
Отдельный clone исходного commit `25e4ff9` с новыми secrets и пустыми volumes прошёл сборку, lint/format, offline/full contract checks, публичный smoke, все 84 собственных теста, полную матрицу из 10 сценариев и публичный persistence с той же сессией. Реальные StartedAt изменились у API, PG, S3, брокера, кэша, worker, relay и LB. SHA-256 каждого установленного Python-модуля совпал с исходниками на обеих API-репликах; OCI revision соответствует проверенному commit. Порты API не опубликованы. Raw второй матрицы — `evidence/clean-pipeline.json`.
После проверки временные контейнеры/volumes и clone удалены. Основной стенд остановлен, его данные сохранены. Финальный commit добавляет только отчёт/доказательства; исходники соответствуют проверенному `25e4ff9`. ЛР1–ЛР4 остались на прежних чистых версиях.
## Соответствие ревизий
После редактуры отчёта, шаблона и служебных метаданных сохранено соответствие прежних и текущих Git-ревизий: [revision-map.json](evidence/revision-map.json). Код приложения, миграции, зависимости, Dockerfile, конфигурация сервисов и исходные публичные проверки не изменены. Численные результаты и исторические image/source identifiers в evidence сохранены в исходном виде; их не следует трактовать как новый запуск измерений.