Files
mtusi2026lab5/REPORT.md
T

32 KiB
Raw Blame History

Лабораторная 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 остаётся сохранённым.

  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 сохраняется в БД. После пятой неудачи автоматических повторов нет.

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.

Заявленные результаты получены запуском сохранённых проверок; ограничения и операторские вмешательства описаны выше.

Финальная проверка самостоятельности

Отдельный 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 сохранены в исходном виде; их не следует трактовать как новый запуск измерений.