Files
mtusi2026lab5/REPORT.md
T
2026-11-16 09:28:38 +03:00

21 KiB
Raw Blame History

Отчёт — лабораторная 5

  • Автор, группа: Никитин Андрей Александрович, БВТ2301
  • Целевой уровень: 5, трек 2 — доказанная идемпотентность versioned pipeline.
  • Commit/PR реализации:
  • Помощь ИИ: Codex, DeepSeek

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

Нужны Linux amd64, Docker Engine с Compose v2, Python 3.10+, доступ к Ubuntu/GitHub для первой сборки. API и worker собираются здесь из C++17; предыдущие lab-образы не используются. При локальной CMake-сборке нужны зависимости из Dockerfile, включая libpqxx >=7.8, hiredis, libsodium, libexif, libwebp и зависимости minio-cpp.

Быстрая проверка в полностью отдельном стенде, без рабочего .env и secrets:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt -r student-tests/requirements.txt
make check validate PYTHON=.venv/bin/python
make test-async PYTHON=.venv/bin/python TEST_ARGS="--output evidence/async-suite.json"

Runner создаёт случайный Compose-проект, синтетические credentials и volumes, проверяет сценарии и удаляет только собственный стенд. Подробнее: student-tests/README.md.

Для обычного локального стенда следующие команды предназначены для чистого clone без существующих .env/secrets. Они генерируют случайные учебные пароли и согласованные file-secrets, не печатая значения:

python3 - <<'PY'
from pathlib import Path
import secrets
assert not Path('.env').exists() and not Path('secrets').exists(), 'Use existing local configuration'
text = Path('.env.example').read_text()
passwords = {k: secrets.token_hex(24) for k in
             ('POSTGRES_PASSWORD', 'MINIO_ROOT_PASSWORD', 'MINIO_USER_SECRET_KEY')}
lines = []
for line in text.splitlines():
    key = line.partition('=')[0]
    lines.append(key + '=' + passwords[key] if key in passwords else line)
Path('.env').write_text('\n'.join(lines) + '\n')
Path('.env').chmod(0o600)
values = dict(line.split('=', 1) for line in lines if '=' in line and not line.startswith('#'))
Path('secrets').mkdir(mode=0o700)
files = {
    'database_url': 'postgresql://'+values['POSTGRES_USER']+':'+values['POSTGRES_PASSWORD']+'@db:5432/'+values['POSTGRES_DB'],
    'cache_url': 'redis://cache:6379/0',
    's3_access_key_id': values['MINIO_USER_ACCESS_KEY'],
    's3_secret_access_key': values['MINIO_USER_SECRET_KEY'],
}
for name, value in files.items():
    path = Path('secrets') / name
    path.write_text(value + '\n')
    path.chmod(0o644)  # container uid 10001; the host parent directory is private
PY

docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# Дождаться HTTP 200:
curl --fail http://localhost:8080/health/ready
make test

Миграции 001–011 выполняются API/worker при старте под общим advisory lock; версия фиксируется в schema_migrations. MinIO init создаёт приватный bucket, а user-init — ограниченного S3-пользователя и policy. Consumer group создаёт worker с позиции 0. Init/migrations допускают повторный запуск с прежними volumes.

Безопасная остановка: docker compose down — named volumes и локальные secrets сохраняются. Намеренный сброс только своего учебного стенда: docker compose down --volumes удаляет его PostgreSQL/Valkey/S3 данные.

Архитектура и решения

Перенесены код и миграции lab4: пользователи, сессии, участники, сообщения, keyset pagination, idempotency, S3 и проверка PNG/JPEG. Общие репозитории, пулы, S3 и изображения собраны в статическую messenger_core. Отдельные бинарники: messenger, worker, операторский job_admin и image smoke tools.

Роль Compose service / версия Persistence и доступ
API api, образ собирается из Dockerfile, 2 реплики по умолчанию Только LB публикует основной HTTP :8080; credentials через file-secrets
Worker worker, тот же образ, /app/worker COUNT 1, одна работа за раз, 512 MiB, watchdog/restart
БД db, postgres:16.15-alpine pgdata, synchronous_commit включён
Брокер/Redis-сессии cache, valkey/valkey:8.1.10-alpine valkeydata, AOF yes, appendfsync always, без host-порта
S3 minio, RELEASE.2025-04-22T22-12-26Z miniodata, приватный bucket, без host-портов 9000/9001
S3 bootstrap minio-init / minio-user-init, mc RELEASE.2025-04-16T18-13-26Z Root используется только bootstrap; API/worker — ограниченный пользователь
LB lb, nginx:1.28.0-alpine Доступ к API-репликам; :8080

SDK MinIO закреплён v0.3.0, stb — commit 013ac3beddff3dbffafd5177e7972067cd2b5083. libwebp/libexif берутся из Ubuntu 24.04. APT-пакеты не закреплены по отдельным версиям; ID протестированных образов есть в evidence. В Docker context исключены .env, secrets, build и приватные файлы.

Upload и durable handoff

Обязательный endpoint — POST /api/v1/chats/{chat_id}/attachments?filename=…, сырые PNG/JPEG bytes, не multipart. Проверяются идентификация/доступ, filename, MIME по содержимому, 10 MiB и 40 млн пикселей до полной распаковки. API проверяет целостность, но resize/crop/WebP выполняет только worker.

API PUT сохраняет оригинал в staging/{chat_id}/{attachment_id}. Затем одной транзакцией сохраняются attachment queued, job и outbox. До COMMIT 202 не выдаётся. Весь upload и PUT остаются синхронными; асинхронна дальнейшая обработка/публикация. Возвращается неизменяемый снимок queued, даже если worker успеет раньше первого GET.

Отдельный поток API выбирает до 32 due outbox через FOR UPDATE SKIP LOCKED, делает XADD и фиксирует published=true. Его пулы независимы от HTTP. COMMIT→XADD восстанавливается из outbox; XADD→COMMIT marker может дать дубль. Доставка at least once; exactly-once не заявляется. payload соответствует contracts/jobs.schema.json: IDs/служебные поля, без bytes, credentials или URL.

В .env.example сессии PostgreSQL. При таком выборе брокер не нужен для upload или readiness: проверяется PostgreSQL. При Redis-сессиях Redis остаётся синхронной зависимостью аутентификации/readiness. Runtime readiness API не выполняет S3 HEAD; S3 имеет отдельный service healthcheck, а upload не подтверждается при ошибке PUT.

Worker, изображения и повторы

Worker читает consumer group attachment-workers через XREADGROUP, подбирает pending через XAUTOCLAIM. Job защищена session advisory lock PostgreSQL, который освобождается при смерти процесса. Размер/SHA-256 staging проверяются до эффектов. Оригинал публикуется из проверенных bytes побайтно, включая возможный EXIF.

Растр декодируется один раз, EXIF orientation применяется, alpha компонуется на белый. Имена итоговых объектов детерминированы. Новые jobs создают три варианта:

Вариант Геометрия Кодирование
thumbnail Вписан в 256×256, без увеличения, floor/min 1 px JPEG, v1 quality 85 / v2 quality 90
crop Центральный квадрат → 128×128, увеличение разрешено JPEG, v1 quality 85 / v2 quality 90
optimized Вписан в 1280×1280, без увеличения, floor/min 1 px lossy WebP, v1 quality 80 / v2 quality 90

EXIF/ICC/XMP в варианты не переносятся. WebP не обязан быть меньше любого маленького исходника. Ready/variants публикуются одной DB-транзакцией после всех четырёх объектов (оригинал + варианты); затем ACK. Дубль ready проверяет объекты и не изменяет результат. Метаданные/SHA оригинала всегда описывают исходные bytes. Content идёт через авторизованный API; без ранее опубликованного результата queued/processing/failed отвечают 409. При upgrade старый ready-снимок сохраняется до успешного COMMIT новой версии.

Временные ошибки сохраняют retries, next_attempt_at и следующий outbox атомарно; после этого ACK старой доставки безопасен. Backoff: ceiling=min(max,base*2^(n-1)), случайная задержка в [ceil(ceiling/2),ceiling], n — номер неудачи текущего бюджета (retries-retry_base); defaults 1000/60000 ms. До due не публикует publisher и не начинает worker. Попытки 1..6 ограничены; постоянный invalid_image/source_mismatch сразу failed, исчерпание — processing_failed. Failed виден в jobs, некорректные события — в jobs:attachments:invalid. Watchdog (default 60 s) завершает зависший процесс с 124, Compose перезапускает его.

Очистка staging и operator replay подробно описаны в infra/worker.md. Ready-staging удаляется после проверки результатов; live presigned URL откладывает удаление до expiry. Failed/orphan retention — 86400 s, период GC — 60 s. Queued/processing и PUT до DB COMMIT защищены, batch GC ограничен. Replay проверяет source checksum, разрешён только failed с сохранённым staging, сохраняет job_id, audit и новый outbox, не сбрасывая монотонный retries. После retention нужен новый upload.

Доказательства критериев

Основная команда — make test-async PYTHON=.venv/bin/python TEST_ARGS="--no-build --output evidence/async-suite.json" (после первой сборки). Все воздействия относятся только к изолированному проекту. JSON содержит контейнеры/StartedAt/volumes, observed checks и source SHA; secrets не сохраняются.

Критерий Воспроизводимый сценарий Наблюдение / evidence
POST 202, состояния, оригинал/thumbnail test_upload_async.sh queued наблюдается при остановленном worker; ready, bytes/SHA и реальный JPEG 256×160 проверены
Durable staging/queue, restart stores test_worker_down.sh сообщение с queued attachment; прежняя сессия и job переживают API/PostgreSQL/Valkey/MinIO restart с прежними volumes
Outbox COMMIT→publish test_outbox_crash.sh exit 86 в реальном API, committed outbox подхвачен после рестарта без нового POST
Publish→marker duplicate test_outbox_crash.sh два события одного job_id, один готовый набор вариантов
Crop/WebP, metadata/download/access Все сценарии ready Реальные JPEG 128×128 и WebP 320×200 fixture; размеры, MIME, SHA, отсутствие EXIF и доступ участников
DB atomicity и bounded retry test_reliability.sh ошибка INSERT outbox откатывает attachment/job; attempts 1..6, backoff/jitter/due и final failed
Replay/DLQ register test_reliability.sh повреждённый source не replay; audit, attempt 7, старое событие не повторяет эффект, ready replay отказан
Crash до ACK, stuck processing test_reliability.sh SIGKILL после S3 и watchdog: восстановление pending, тот же эффект
Ограниченная конкуренция/идемпотентность test_reliability.sh 2 worker на дублях, 2 API-публикатора на outbox, без второго набора вариантов
GC и retention test_reliability.sh ready/orphan/expired failed удаляются, queued/live presigned и PUT→COMMIT защищены
Память test_reliability.sh RGB PNG 8000×5000 обработан при 512 MiB без swap; это не измерение RSS всех возможных форматов
Публичный API Завершение каждого shell-теста Неизменённый tests/smoke.py проходит
Схемы make check validate Offline structure и полная OpenAPI 3.1 / JSON Schema validation проходят

Сводка полного прогона: evidence/async-suite.json. Финальный прогон 15.11.2026 (Europe/Moscow): Python 3.14.4, Pillow 12.1.1, 18 групп проверок, 121.048 s вместе с запуском/удалением стенда. Cleanup контейнеров, volumes, сети и disposable credentials отдельно подтверждён. Отдельный upload-прогон со сборкой: evidence/upload-async.json. Геометрия/EXIF/alpha отдельно проверяются test_thumbnail.py и test_variants.py; команды и зависимости — в student-tests/README.md.

Методика и ограничения

Проверки функциональные, не нагрузочный эксперимент. Основной fixture — 320×200 PNG, 111817 bytes, SHA-256 из tests/fixtures/README.md. Memory fixture — один синтетический 8-bit RGB PNG 40 млн пикселей. По умолчанию worker serial, для дублей временно запущены 2 процесса; неограниченного prefetch нет. В тестовом override API получает 512 MiB/1 CPU, timeout worker — 3 s, retry base/max — 200/800 ms, GC — 1 s; рабочие defaults сохранены в Compose. Фактические image IDs/лимиты и elapsed test run находятся в JSON evidence. RPS, p50/p95/p99 и статистический memory benchmark не измерялись.

Не выдерживается потеря DB/S3/брокер volumes или самого единственного хоста; это не HA-кластер. Сессии Redis при остановке общего Valkey недоступны, поэтому outbox fault-tests используют PostgreSQL-сессии. При выключенных API-публикаторах outbox/retry остаётся durable, но не публикуется до запуска API. Рабочий стенд учебный HTTP; lab7 TLS и rate limiting сюда не входят. Готовые записи предыдущих шагов сохраняют прежние варианты; обновление pipeline не откатывает ready автоматически. Публикация кода/commit/PR не выполнялась.

Уровень 5: трек 2

Гипотеза, инварианты, модель отказов, алгоритм защиты и границы результата: infra/track2.md. Для v1/v2 используются раздельные S3 namespaces, unique jobs/results на attachment/version и повторная проверка desired version под row lock перед переключением published pointer. Source/recipe захвачены из job; carrier не может подменить версию записи БД. Legacy storage keys продолжают читаться.

make test-track2 PYTHON=.venv/bin/python \
  TEST_ARGS="--output evidence/track2.json"
# Повтор уже собранного неизменённого кода:
make test-track2 PYTHON=.venv/bin/python \
  TEST_ARGS="--no-build --repetitions 3 --output evidence/track2.json"

Исследование использует три независимых холодных Compose-стенда и фиксированную матрицу доставок/отказов. Каждый повтор включает 16 валидных uploads, 27 логических jobs для версий 1/2 и проверки результатов после рестарта PostgreSQL/Valkey/MinIO/API. Четыре crash points выполняются для обеих версий. Отдельно старый worker останавливается до эффекта, после эффекта и после COMMIT; v2 завершается на втором worker, затем тот же старый процесс возобновляется. Сравниваются actual S3 SHA, метаданные, version pointer, PK counts и terminal states всех committed intents.

Сводка итоговых повторов: evidence/track2.json. В ней хранятся source/method SHA, image IDs, фактические Docker die exit codes, хеши versioned объектов, результаты инвариантов и время каждого повтора. Измерения RPS/p95/RSS не заявляются: это выбранный трек идемпотентности.

Повтор Проверки Attachments / jobs Время со стендом, s Итог
1 20 16 / 27 187.385 PASS
2 20 16 / 27 185.107 PASS
3 20 16 / 27 187.243 PASS

Итог 15.11.2026 (Europe/Moscow): 48 принятых вложений, 81 committed job, 24 подтверждённых crash с exit code 86 и 9 возобновлений старого процесса после публикации v2. Потерянных вложений, незавершённых jobs и дублей result rows — 0; новый снимок не изменился после поздней работы v1. Все три стенда и их credentials удалены. Гипотеза подтверждена в описанной модели отказов; исчерпывающий перебор распределённых расписаний не выполнялся.

Exactly-once доставка не заявляется: XADD/PUT могут повторяться после crash. Защищён один логический результат (attachment_id,pipeline_version,variant) и монотонное переключение опубликованного снимка. Изоляция ключей защищает bytes v2 от поздних PUT v1; CAS защищает DB pointer от позднего COMMIT v1. Исторические versioned outputs сохраняются, их retention пока не задан. Два HTTP-запроса по versionless endpoint вокруг upgrade могут увидеть разные published snapshots; обязательный API не расширен новым version-download контрактом.

Источники и библиотеки