32 KiB
Лабораторная 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 диска. Соседние лабораторные не нужны.
Команды выполняются из корня клонированного репозитория.
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:
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. Не запускайте одновременно сценарии, меняющие состояние одного стенда. Выходной файл должен быть новым, предыдущие доказательства не перезаписываются.
Реальная проверка возраста и очистки:
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 моделирует возраст метаданных отдельно, не заменяя эту проверку.
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.
Архитектура и транзакционные границы
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 остаётся сохранённым.
- API проверяет сессию/чат, имя, MIME, фактический поток <=10 MiB, время приёма <=15 s, целостность PNG/JPEG, <=40 млн пикселей. Pixel guard действует до полной распаковки. На API один upload slot, ожидание <=5 s, затем 429. Временный файл в tmpfs не является durable staging.
- БД создаёт upload reservation с lease 120 s. Проверенный оригинал записывается в persistent private S3
staging/<UUID>. Имя клиента не используется как ключ. PUT имеет ограниченные socket timeouts без автоматических повторов. - Одна PG-транзакция блокирует/проверяет reservation, создаёт attachment=queued, job и outbox, отмечает handoff. После COMMIT API возвращает 202 со снимком queued. Thumbnail ещё не обещан; worker может успеть завершить до первого GET.
- Relay выбирает due outbox через
FOR UPDATE SKIP LOCKED, делает XADD, затем фиксирует published_at. Потеря ответа XADD/COMMIT вызывает повтор с тем же job_id. До шага 3 возможен непринятый orphan: общей транзакции S3+PG нет. Reservation и retention GC закрывают это окно без ложного 202. - 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.
- Worker сверяет исходный размер/SHA-256, повторно валидирует изображение, сохраняет original и три варианта в
objects/<attachment>/v<version>/<variant>. После всех PUT атомарно публикует метаданные при совпадении текущей версии, fence и действующего lease. - 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 сохраняется в БД. После пятой неудачи автоматических повторов нет.
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, XAUTOCLAIM, XACK, persistence.
- RabbitMQ reliability, confirms/acknowledgements — теория границ, RabbitMQ в стенде не используется.
- PostgreSQL row locks, SKIP LOCKED.
- Pillow ImageOps, file formats.
- MinIO source pin, mc source pin.
Заявленные результаты получены запуском сохранённых проверок; ограничения и операторские вмешательства описаны выше.
Финальная проверка самостоятельности
Отдельный 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. Код приложения, миграции, зависимости, Dockerfile, конфигурация сервисов и исходные публичные проверки не изменены. Численные результаты и исторические image/source identifiers в evidence сохранены в исходном виде; их не следует трактовать как новый запуск измерений.