21 KiB
Отчёт — лабораторная 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 контрактом.
Источники и библиотеки
- Контракт и состояния, attachment-states, jobs schema.
- minio-cpp v0.3.0, hiredis, libpqxx.
- stb, закреплённый commit, libwebp, libexif.
- libsodium — KDF/сессии/контрольные суммы; Pillow — независимое декодирование в тестах. Код lab4 перенесён из соседнего репозитория