Files
mtusi2026lab5/REPORT.md
T

32 KiB
Raw Blame History

Лабораторная 5 — очереди и асинхронные изображения

Майорова Софья, БВТ2301. Целевая оценка: 5. Трек 2 — доказанная идемпотентность versioned pipeline. Выполнено 27 октября 2026 года. Оценку подтверждает преподаватель.

Продолжено моё решение lab4, PR 18. Сохранены две API за LB, сессии PostgreSQL, Redis-кэш, keyset-пагинация, идемпотентность сообщений и приватные S3-вложения. Upload изменён по контракту: 202 queued после устойчивого staging и сохранения задания; resize выполняется отдельным worker. Исходные README/COURSE/contracts/tests не менялись.

Запуск из чистого clone

Нужны Docker Engine/Compose v2 и Python 3.9+ для публичных тестов на хосте. Сервер/worker — Python 3.12.8 внутри Docker. На этом Mac:

colima start --profile mtusi-labs
export DOCKER_CONTEXT=colima-mtusi-labs
cd "/Users/ssmayorova/Documents/Учеба/Высоконагруженные приложения/lab5"
python3 scripts/bootstrap.py
docker compose build api
docker compose up -d --wait
export BASE_URL=http://127.0.0.1:18091
python3 scripts/wait_ready.py
make check test test-student BASE_URL=$BASE_URL

На другой машине клонировать публичный форк lab5 и выбрать solution/BVT2301-Mayorova, затем выполнить те же команды из корня clone. build api идёт первым: migrate, worker, dispatcher и tools используют тот же построенный образ. Одноразовый migrate под advisory lock применяет 001–005; API DDL не выполняют. Bucket-bootstrap идемпотентно создаёт приватный bucket. После них поднимаются API, dispatcher и worker.

Bootstrap создаёт случайные локальные пароли и ключи, сохраняет существующие значения и .env, пересобирает только генерируемую конфигурацию identities из этих ключей. Каталог secrets — 0700; полный s3_config — 0600, монтируется только root S3 gateway. Отдельные ключи процесса читаются UID 10001 внутри контейнера; их файлы находятся в закрытом 0700-каталоге хоста. API не получает worker/admin credentials. .env, secrets, build и данные исключены из Git и build context.

Остановка с сохранением данных: docker compose down. Только для намеренного удаления ненужных учебных данных данного проекта — docker compose down -v. В restart/failover volumes не удаляются. Изолированный clean-clone стенд использует другое имя проекта, порт и временные volumes, которые удаляются после его проверки.

Архитектура и границы подтверждения

Клиент → LB → API × 2 → PostgreSQL (сессии, чаты, сообщения, attachments + jobs/outbox)
                   ├→ Redis cache профилей (восстанавливаемый)
                   └→ S3 staging (полные исходные bytes)
                              ↑
PostgreSQL jobs/outbox → dispatcher → Redis Streams broker (AOF always)
                                          ↓ XREADGROUP / XAUTOCLAIM
                                        worker → изолированный render subprocess
                                          ├→ конечный S3 results/<attachment>/vN/...
                                          └→ атомарный ready + варианты в PostgreSQL → XACK + XDEL

S3 — SeaweedFS 4.51: отдельный gateway и mini master/volume/filer на сети storage. И байты, и filer metadata устойчиво находятся в s3_data; API не имеет доступа к filer, административный UI/WebDAV отключены. PostgreSQL — другой volume. Брокер — отдельный Redis 7.4.1, не кэш: AOF, appendfsync always, noeviction, persistent broker_data, без публикации порта на хост. Кэш остаётся disposable Redis без AOF. Единственная публичная точка — LB на 127.0.0.1:18091.

Образы Python 3.12.8, PostgreSQL 17.2-bookworm, Redis 7.4.1-bookworm, HAProxy 3.0.5-alpine и SeaweedFS 4.51 закреплены digest в Dockerfile/Compose. Например, SeaweedFS: sha256:f7a49e3f3972ebed5be2ed4befa4a0c68eb7bdddba6e692d42729ceb545134b8. Pillow 13.0.0, boto3 1.40.61, psycopg/redis и транзитивные зависимости закреплены в requirements.txt. Это проверенный набор версий, не обещание отсутствия будущих уязвимостей.

Процесс CPU Память Состояние
API, каждая из двух 1 256 MiB Без устойчивых локальных originals
Worker, concurrency=1 1 768 MiB Временный tmpfs; источник/результат в S3
Dispatcher 1 256 MiB Устойчивый outbox в PostgreSQL
PostgreSQL 1 512 MiB postgres_data
Broker 0,5 192 MiB, maxmemory=96mb/noeviction broker_data/AOF
S3 store / gateway 1 / 0,5 512 / 512 MiB s3_data / без собственных originals
LB / cache 0,5 / 0,25 64 / 64 MiB Нет обязательных устойчивых данных

Сумма CPU-лимитов превышает 4 vCPU локальной VM: это overcommit, не выделенные физические ядра. Измерения проводились на macOS arm64, Colima/Linux с 4 vCPU и примерно 4 GiB RAM. Ранее запущенные учебные стенды не останавливались.

Что сохранено при 202

API проверяет Bearer/доступ к чату, Content-Length ≤10 MiB, допустимый filename/MIME, реальный PNG/JPEG header, размеры ≤40 млн pixels и verify(). Исходник читается кусками 64 KiB в ограниченный временный файл, SHA-256 считается потоково. Полного декодирования/resize в API нет. Поэтому JPEG с корректным заголовком, но повреждённым scan data может быть принят и затем завершиться failed invalid_image в worker; заведомо чужой формат/несовпадение MIME отклоняется 415, лимиты — 413, опасное имя — 400.

Перед PUT фиксируется internal intent uploading со случайным UUID, server-generated staging key и ожидаемой checksum. Под row lock выполняется полный PUT в приватный staging/<UUID>. В одной следующей транзакционной границе с этим lock создаётся queued job/outbox и меняется Attachment на queued с current_job_id. COMMIT выполнен до 202. API возвращает сохранённый queued snapshot даже если worker успел закончить раньше HTTP-ответа. Bytes в PostgreSQL и broker не помещаются. Временный файл API не является долговременным staging.

Уже принятая работа не зависит от RAM API или доступности dispatcher/broker в этот момент. Readiness API проверяет PostgreSQL и S3; остановленный worker/broker не запускает resize в HTTP. При MAX_PENDING_JOBS=100 новые uploading/queued/processing ограничены общим счётчиком PostgreSQL под advisory lock; заполнение даёт 503. Это предел количества, не расчёт disk quota. Неподтверждённый upload не следует прозрачно повторять: контракт идемпотентности относится к POST messages.

Transactional outbox и at-least-once

Таблица attachment_jobs совмещает job registry и transactional outbox. Создание job и queued Attachment атомарно. Dispatcher выбирает due rows FOR UPDATE SKIP LOCKED, выполняет XADD с envelope по jobs.schema.json, затем отмечает published_at. При сбое до XADD строка остаётся; после XADD до фиксации marker возможен дубль. XADD response с AOF always подтверждает приём/сохранение брокером согласно его политике. Это ещё не подтверждение обработки изображения.

Worker читает consumer group image-workers, count/prefetch=1 на slot. XAUTOCLAIM возвращает зависшую pending delivery после lease. Dispatcher также восстанавливает processing с истёкшей lease и повторяет долго не захваченную queued publication. DB-инварианты, а не предположение о единственности сообщения брокера, определяют допустимость обработки.

Broker message содержит только schema_version, job_id, type, attachment_id, pipeline_version, attempt, created_at; допускается контрактный trace carrier. Пример фактически проверенного envelope — 243 bytes. Ключи хранилища и credentials берутся worker из доверенных настроек/БД, произвольные URL/filename-пути из сообщения не исполняются. Неверный envelope наблюдаем в ограниченном rejected-jobs stream: только причина, исходный message ID и hash, без сохранения произвольного payload. Подтверждение ошибочного envelope происходит после записи этой DLQ-записи.

XACK + XDEL выполняются одной Redis Lua-операцией после устойчивого ready/failed либо безопасного no-op. При потере ack доставка повторяется. Ошибка БД, не позволившая сохранить результат/ошибку, не подтверждает delivery. Доставка остаётся at-least-once; сокращение числа логических эффектов не превращает её в exactly-once.

Worker, варианты, retry и lease

Worker — отдельный контейнер/процесс. Default concurrency=1, конфигурация допускает 1–2; при увеличении нужно отдельно увеличить/измерить WORKER_MEMORY, в отчёте проверен только 1. Производственная lease — 60 s; дочерний renderer ограничен wall timeout 20 s, CPU 15 s (hard 16), virtual address space 512 MiB. Worker контейнер ограничен 768 MiB, tmpfs 128 MiB. Исходник ≤10 MiB скачивается кусками с SHA-256/size и deadline 15 s; S3 connect/read timeouts — 1/3 s, SDK total attempts=1. Самостоятельные retry контролирует job registry.

Pillow полностью декодирует исходник в изолированном subprocess, проверяет pixels до load, применяет EXIF orientation, alpha композитит на белом. Размеры рассчитываются с округлением вниз, min 1 px. Для thumbnail/optimized маленький исходник не увеличивается. Варианты сохраняются без EXIF/ICC:

  • thumbnail: JPEG quality=85, вписан в 256×256; fixture 320×200 → 256×160;
  • crop: центрированный квадрат 128×128, Lanczos; маленький исходник допускает увеличение;
  • optimized: WebP, вписан в 1280×1280, method=4, quality=82 для pipeline v1, quality=70 для v2. Уменьшение каждого маленького файла не обещается.

Оригинал публикуется побайтно в конечный S3-prefix отдельно от staging. Ready фиксируется только после original + всех трёх вариантов с checksums/размерами. GET content для queued/processing/failed даёт 409, для чужого attachment — 404. Сообщение может ссылаться на queued/processing своего чата, failed прикреплять нельзя. Download остаётся авторизованным proxy через API без redirect.

Attempt увеличивается только при успешном claim; job_id при redelivery/retry не меняется. По умолчанию максимум 5 попыток на job. Временные storage/timeouts/processing failures возвращают queued с backoff min(8, 0.5*2^(attempt-1)) + U(0,0.5) секунд; постоянные invalid_image/source_missing/checksum_mismatch/result_conflict сразу дают failed. Исчерпание бюджета — failed retry_exhausted. В публичной ошибке нет exception details. Реестр failed и job_events доступны оператору, не клиенту.

Повторная delivery уже ready/failed — no-op. Busy/early duplicate не отбирает чужой lease. Истёкший lease снимает ownership и создаёт следующую управляемую попытку. Final COMMIT проверяет current_job_id, pipeline_version, state, lease_token и срок lease; потерявший аренду worker не может опубликовать старый результат.

Версионирование и инварианты трека 2

Ключ эффекта: (attachment_id, pipeline_version, variant). Ключи объектов: results/<attachment>/vN/original|thumbnail|crop|optimized. PUT результата условный If-None-Match: *; готовый объект с совпадающими size/hash повторно не пишется, конфликтующий не затирается. Результаты детерминированы закреплённым renderer и параметрами версии.

Операторский переход на следующую реализованную версию атомарно помечает старую job superseded, создаёт новую queued job с отдельным job_id и обновляет current_job_id/version. Источник новой job — устойчивый исходник прежней версии либо staging, а не локальный файл API. Сейчас реализованы только v1 и v2; публичный upload создаёт v1.

Проверяемые инварианты:

  1. Подтверждённая queued задача сохраняется после смерти API и рестарта broker.
  2. Одновременный дубль допускает единственный claim; serial duplicate/reorder не увеличивает число успешно опубликованных вариантов.
  3. Падение до/после S3 side effect и до/после результата БД не теряет исходник и не создаёт второй набор объектов той же версии.
  4. Устаревшая delivery и уже выполняющийся старый worker не возвращают ready в processing и не затирают результат новой версии.
  5. Failed наблюдаем, retries конечны; replay допускается только для текущей failed job с доступным source и оставляет audit.
  6. Cleanup не удаляет staging текущей queued/processing работы или свежей failed.

student-tests/pipeline_checks.py выполняет настоящие операции PostgreSQL/S3/Redis и завершает отдельные worker/publisher-процессы через os._exit(77) в явных операторских fault points. Это не публичный HTTP hook. Проверены: COMMIT без publisher; publisher после XADD до outbox marker; worker before_side_effect, after_original, after_objects, after_commit; повтор/перестановка envelope; два concurrent consumer; pause старого subprocess после записи всех объектов → завершение v2 → продолжение v1, получающее fenced no-op; поздняя v1 delivery после ready v2.

Для первого crash действительно ожидается истечение тестовой lease=5 s; в двух следующих случаях deadline той же тестовой строки ускоряется SQL-изменением lease_until, чтобы не тратить по 60 s. Это воздействие теста на новые собственные job IDs, не подмена результата. Production lease=60 s не изменяется. После каждого crash выполняется реальный Redis pending reclaim/ack; в соответствующем prefix остаётся ровно четыре объекта. После after_commit новая delivery не увеличивает attempt.

Transient failure воспроизводится настоящим S3 отказом подписи с заведомо неверным тестовым ключом: budget=2 только для этой job, затем queued → failed retry_exhausted, после явного replay с правильными credentials — ready на attempt 3. Повреждённый JPEG доходит до постоянного failed invalid_image. Проверены EXIF-поворот, прозрачность на белом, отсутствие EXIF в thumbnail и запрет увеличения маленького thumbnail.

Команда исследования, только на синтетическом стенде (останавливает фоновую обработку, не API):

docker compose stop worker dispatcher
docker compose run --rm -T --no-deps -v "$PWD:/work:ro" -w /work audit python student-tests/pipeline_checks.py
docker compose up -d --no-deps worker dispatcher

audit — tools profile, не запускается обычным up. Только он получает дополнительные локальные секреты для операторских/негативных проверок; API их не получает. Исследование автоматически создаёт новые synthetic users/chats/jobs, не изменяет чужие.

Операторские команды и очистка

# Наблюдаемый реестр failed:
docker compose exec worker python src/admin.py failed
# Явный replay текущей failed job; UUID взять из предыдущей команды:
docker compose exec worker python src/admin.py replay JOB_UUID
# Новый pipeline для конкретного вложения:
docker compose exec worker python src/admin.py version ATTACHMENT_UUID --version 2
# Dry-run и явное применение cleanup:
docker compose exec worker python src/admin.py cleanup
docker compose exec worker python src/admin.py cleanup --apply

Replay не сбрасывает счётчик, не повторяет ready и не создаёт новую копию успешной job: явно добавляет новый бюджет попыток к тому же job_id, сохраняя историю. Необходим доступный source; после истечения retention может понадобиться внешнее восстановление исходника.

Staging удаляется только после COMMIT ready. Crash после COMMIT до очистки безопасен: операторский cleanup идемпотентно удаляет оставшийся staging готовой работы. Failed/незавершённый uploading хранится минимум 24 h; queued/processing никогда не собираются. Cleanup использует row locks/SKIP LOCKED и фильтр managed staging prefix; dry-run без --apply ничего не меняет. Счётчики cleanup отражают кандидаты по метаданным: часть staging objects уже удалена worker, повторная очистка безопасна. Реестр и сообщения не удаляются вместе с исходником. Неактуальные immutable outputs старых версий пока сохраняются — автоматическая уборка old-version results не заявляется.

Результаты и воспроизводимость

Критерий Проверка и наблюдение Evidence
Публичный минимум lab5 Smoke: 202, ready, исходный SHA-256 и настоящий JPEG thumbnail final-tests.txt
Прежний API и собственные изображения 18 собственных тестов PASS: Unicode/NUL, auth, гонки/idempotency, variants, ACL, MIME/bytes/pixels/filename student-tests.txt, final-tests.txt
Устойчивый staging/очередь Worker/dispatcher остановлены, upload 202 и message; обе API убиты SIGKILL до publish; после рестарта со старым Bearer всё сохранено durability.json
Persistence broker Настоящий Redis Streams XADD; до/после restart с volume — 1/1 запись; затем та же job ready durability.json
Полный restart API/LB/worker/dispatcher остановлены, PostgreSQL/cache/оба S3/broker перезапущены с volumes; старые сессия и bytes сохранены persistence.txt, restart-before/after.json
Отказ API 2 реплики, 114 подтверждённых writes, 2 переходные ошибки, восстановление 2,534 s failover.txt
Все уровни retry/final/replay Реальные S3 signature failures, конечный budget=2, audit/replay и готовый результат на attempt 3 pipeline.json
Outbox и worker crash windows Отдельные процессы exit 77, реальные redelivery и четыре объекта на версию pipeline.json
Reorder, concurrent duplicate, stale version 13 групп assertions/invariants; old running process fenced, new ready не изменился pipeline.json
Изображения и лимиты worker EXIF/alpha/small-image, malformed JPEG failed, 40 Мп RGB ready, subprocess/container limits pipeline.json, resources.json
Cleanup Dry-run/apply/repeat, защита активного source и свежих failed pipeline.json
Приватность Anonymous known-key GET/list →403; в envelope только 7 служебных полей, проверены неверные типы/форматы security.json
Полная валидация схемы OpenAPI 3.1 / JSON Schema PASS openapi.txt
Чистый clone Отдельные новые секреты, проект, порт и пустые volumes PASS: новые секреты и пустые PG/S3/broker volumes, 18 тестов, SIGKILL API с queued work и полный restart; clean-clone.txt

Все сценарии сохраняют tokens только в памяти теста. Snapshot содержит разрешённые поля state/started_at/mounts/resources, не environment или secret values. Fault injection и операторские команды воспроизводимы из репозитория. Дополнительные команды:

export BASE_URL=http://127.0.0.1:18091
python3 student-tests/durability.py
python3 student-tests/resources.py
make test-failover ACTION_SCRIPT=scripts/stop-one.sh BASE_URL=$BASE_URL
docker compose up -d --wait --no-deps api
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=$BASE_URL

Измерение ресурсов и задержек

Это дополнительная проверка bounded worker, не заявка на трек 1. Concurrency/prefetch=1, один прогон на профиль, по 10 одновременно начинающих клиентов. Генерация PNG до измерения; отправляется реальное тело, без скрытых retry. Worker перезапускается перед профилем, cgroup peak относится к этому запуску. Считается время HTTP-accept и время до наблюдаемого ready; polling добавляет до примерно 0,3 s. Для N=10 nearest-rank p95/p99 равны максимуму. Сэмплер docker exec также вносит overhead, closed-loop не даёт верхней границы production throughput.

Pixels / bytes 202: p95 До ready: p50 / p95=p99 Worker cgroup peak / resident anon Успех
64 000 / 1 294 0,080 s 1,834 / 2,923 s 78,81 / 76,82 MiB 10/10
2 520 000 / 7 563 763 1,102 s 4,155 / 7,025 s 123,46 / 112,50 MiB 10/10
40 000 000 / 533 859 0,092 s 6,826 / 11,659 s 253,67 / 251,36 MiB 10/10

После исследования и восстановления очередь полностью опустела: 85 ready, 3 намеренно failed из-за повреждённых JPEG, 0 queued/processing/uploading, 0 stream entries/pending deliveries; у всех ready по три варианта (jobs-summary.json).

Все 30 приняли 202 и достигли ready; OOM kill=0. memory.peak — kernel cgroup максимум контейнера, включая renderer, tmpfs/cache/kernel; resident anon взят как максимум memory.stat anon среди samples, это не точный максимальный RSS каждого отдельного PID. CPU counters также сохранены в raw samples. Маленький сжатый файл 40 Мп занимает больше RAM/CPU при декодировании, чем более крупный файл с меньшим количеством pixels. Быстрый 202 не означает мгновенный thumbnail: работа проходит ограниченный worker и ждёт очередь.

Задержка и память отдельного worker

Основной исследовательский результат трека 2: все внедрённые crash/duplicate/reorder/version сценарии соблюли заявленные инварианты; умирающий после COMMIT worker не заставил повторно публиковать эффект, а живой, но устаревший worker получил fencing вместо перезаписи новой версии. Это измеренная функциональная проверка, не статистическое доказательство отсутствия всех гонок.

Для графиков: Python 3.11+, pip install -r requirements-research.txt, python student-tests/plot.py. PNG/SVG уже приложены. Workflow Application добавляет сборку/стенд/smoke/own tests/failover/persistence; hosted CI отдельно не объявляется прошедшим без результата платформы.

Ограничения

Один host/PostgreSQL/S3-store/broker/LB остаются точками отказа. Доказаны процессные сбои и restart с volumes, не потеря диска/всего хоста или гарантия power-loss durability. HTTP и неподключённые к хосту backend-порты допускаются только для локального синтетического стенда; удалённой публикации без TLS нет. Docker operator имеет доступ к секретам.

Существующий immutable результат проверяется по HEAD size/hash metadata, не повторным чтением всего объекта; защита от произвольной подмены привилегированным S3-оператором не заявляется.

Нет распределённой ACID-транзакции. Outbox и периодическая republish закрывают разрывы повтором, поэтому сообщения/CPU могут дублироваться; fences и immutable versioned keys защищают опубликованный результат. Потерявшийся worker может ещё некоторое время тратить CPU до timeout/завершения, но не публиковать старый ready. Нормальные bounded render заканчиваются до lease; выбирая меньшую lease, надо отдельно измерять нагрузку.

Состояния jobs/events и неактуальные versions накапливаются. Cleanup запускает оператор, не скрытый scheduler. Retention failed sources ограничивает возможность replay без внешней копии. Принятая задача может закончиться failed из-за постоянной ошибки или исчерпания retry; это наблюдаемое завершение, а не исчезновение работы. Image parser ограничивает декодированные PNG-текстовые метаданные 1 MiB. Антивирус и UI не входят в работу.

Источники и ИИ

Собственное решение lab4 (Майорова Софья, PR 18); чужие студенческие решения не копировались. Задание и contracts текущего skeleton — основание обязательного поведения.

Codex использован для реализации, тестов, fault-injection, запуска измерений и оформления. Все PASS/числа получены реальными командами, границы их применимости приведены выше.