Files
2026-11-06 21:15:31 +03:00

32 KiB
Raw Permalink Blame History

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

  • Автор, группа: Иванов Данил, БВТ2301 (перенесено из отчёта lab4).
  • Целевая оценка: 5, трек 2 — доказанная идемпотентность pipeline.
  • Форк: https://gitea.privcloud.tech/landcruiser200/mtusi2026lab5. Основа задания — 276dbdad8a34da4c5b57fbf1879ca169b581d75b; реализация перенесена из lab4 cc0ef71. Результаты относятся к рабочему дереву, исходники зафиксированы SHA-256 в evidence. PR не опубликован.
  • Дата: 06.11.2026, Europe/Moscow. Использована помощь Codex: перенос, реализация, проверки, анализ и отчёт. Первичные материалы: контракт, состояния, схема job, Redis Streams, Pillow ImageOps.

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

Требуются Docker Desktop с Linux containers, Docker Compose v2 с поддержкой !override, Python 3.9+ для публичных проверок. Для дополнительных image-тестов и style checks нужны Python 3.10+ и зависимости requirements-tools.txt. Для локальных Java-тестов — JDK 21; Docker собирает Java из исходников через Gradle Wrapper 9.3.0, скачанный вручную zip не требуется.

pwsh -File scripts/bootstrap.ps1
docker compose config --quiet
docker compose up -d --build
# Дождаться двух healthy API и HTTP 200 /health/ready.
$env:BASE_URL='http://127.0.0.1:8080'
py tests/smoke.py

На этом Windows-хосте 8080 попал в зарезервированный ОС диапазон. Поэтому для запуска и измерений использован отдельный override, меняющий только публикацию порта:

docker compose -f docker-compose.yml -f compose.local.yaml up -d --build
$env:BASE_URL='http://127.0.0.1:18085'
py tests/smoke.py
py tests/resilience.py --mode persistence --action-script scripts/restart.cmd
py tests/resilience.py --mode failover --action-script scripts/stop-one.cmd
docker compose -f docker-compose.yml -f compose.local.yaml up -d api

API по-прежнему две реплики. Параметры существующих PostgreSQL/Redis/MinIO/LB, сеть, volumes и лимиты API перенесены из lab4. Добавлены необходимые для lab5 broker, worker и dispatcher outbox. Репозиторий lab4 и его .git не изменялись; у lab5 собственная история и origin форка.

Bootstrap идемпотентно создаёт локальные secrets и .env, не перезаписывая имеющиеся значения. Пароли генерируются локально, не печатаются и исключены из Git. В исходниках ровно одна миграция V1__init.sql: таблицы сразу создаются в конечном виде. На чистой БД Flyway применяет V1; две реплики координируются блокировками Flyway. Bucket bootstrap создаёт приватный bucket и отдельные ограниченные S3 credentials. MinIO console выключена, внутренние порты наружу не опубликованы.

По просьбе пользователя V2–V4 свёрнуты в V1. Проверка check_migration.py применяет V1 к временной БД и сравнивает pg_dump --schema-only с существующим стендом, исключая только историю Flyway и случайные restriction tokens. Схемы совпали: stdout, SHA и результат. Затем проверены настоящий Flyway migrate/validate и два конкурентных клиента инициализации на пустой БД: fresh Flyway.

В существующем учебном volume данные сохранены. История V1–V4 предварительно сохранена локально в игнорируемом .gradle/flyway-consolidation/history-before.json; после доказанного равенства схем однократно выполнен Flyway repair. Для маркировки удалённых будущих V2–V4 использован пустой ignoreMigrationPatterns; эти версии получили DELETED, V1 — SUCCESS. Это операторское согласование уже применённой локальной истории, не автоматический repair при запуске приложения. Журнал repair, сохранность количеств строк и история, перезапуск двух API.

Полный основной прогон ниже выполнен до свёртки SQL; Java/Python-код приложения при свёртке не менялся. После неё повторены чистая Java-сборка, smoke, core pipeline и проверки межоперационных блокировок: Java, smoke, core, boundaries. Docker-сборка с единственной V1. SHA исходников и environment пересняты после свёртки.

Остановка с сохранением данных: docker compose down. Намеренное удаление учебных данных: docker compose down -v — не часть проверок. Для Linux hooks .sh требуется chmod +x. Детальные команды экспериментов — tests/README.md.

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

Клиент → nginx → Java API ×2 → PostgreSQL + приватный S3 staging. API атомарно фиксирует Attachment, ProcessingJob и Outbox в PostgreSQL после успешного S3 PUT. Только после COMMIT возвращается снимок 202 queued. Ресайз API не выполняет; в очередь можно принимать работу при остановленном worker/broker, пока доступны БД, S3 и бюджет незавершённых jobs.

Dispatcher читает outbox с FOR UPDATE SKIP LOCKED и публикует ID/версию/попытку в отдельный Redis Streams broker. Broker использует AOF и appendfsync always; consumer group читает с COUNT=1, прежде новых сообщений обрабатываются собственные pending; активный consumer держит одну доставку. Незавершённая текущая попытка не ack-ается. Выдача XADD означает приём брокером, а XACK выполняется worker после устойчивого эффекта. Это разные границы. Неопределённый publish допускает redelivery. Lua атомарно связывает XADD с индексом (job_id, managed attempt): watchdog не размножает ожидающую работу при остановленном worker. ACK удаляет индекс только при совпадении stream ID, поэтому поздний ACK не удаляет публикацию следующей попытки. Outbox сохраняется в БД и повторно публикует текущую QUEUED работу, а также восстанавливает истёкшие leases. Поэтому рестарт broker или разрыв COMMIT/publish не требуют создавать новую job вручную.

Worker — отдельный Python-процесс, две реплики, каждая запускает не более одного дочернего image-процесса. Дочерний процесс проверяет исходный SHA-256/размер, MIME и пиксели, применяет EXIF orientation, сохраняет оригинал и три варианта. Parent ограничивает время процесса, Linux address space ограничен 768 MiB; container limit — 1 GiB. При превышении времени процесс уничтожается, сообщение остаётся без ack, lease восстанавливает работу. Prefetch и число процессов ограничивают RAM и неконтролируемый параллелизм.

Pipeline v1: thumbnail JPEG ≤256×256 без увеличения, crop JPEG 128×128 по центру, optimized WebP ≤1280×1280 без увеличения. Размеры рассчитываются целочисленно с округлением вниз. Filename ограничен Unicode code points; response header buffer LB 8k поддерживает Content-Disposition для допустимого имени из 255 четырёхбайтовых символов. Alpha компонуется на белый фон, EXIF/ICC не передаются в выходные изображения. Качество JPEG=85, WebP=80. В v2 JPEG=90 и WebP=85, геометрия сохраняется. Уменьшение каждого маленького файла не обещается. Обновление алгоритма/кодека требует новой pipeline_version.

Эффект идентифицируется (attachment_id, pipeline_version, variant): уникальный ключ manifest в БД и content-addressed S3 keys с prefix версии. Повтор той же обработки пишет те же байты в те же ключи. Старая версия не пишет в prefix новой. Публикация manifest, READY и результата job выполняется одной транзакцией после проверки текущей версии, token lease и срока аренды под блокировкой строк. Истёкший или устаревший worker не может опубликовать READY/FAILED поверх нового результата. GET метаданных использует REPEATABLE READ. Content берёт shared cleanup fence до чтения метаданных и использует READ COMMITTED, чтобы ожидание блокировки не закрепило устаревший snapshot; выбранные immutable keys защищены до копирования bytes. Статус вложения при создании Message защищён FOR SHARE до COMMIT; queued/processing/failed content возвращает 409.

Retry: production-бюджет 5 попыток, экспоненциальный backoff до 30s с jitter 0–1s. Некорректное изображение — постоянная ошибка; сетевой/временный отказ повторяется, после исчерпания — FAILED с безопасным error_code. Реестр failed — PostgreSQL processing_jobs и API metadata. python -m pipeline.operator replay UUID доступен оператору через Docker exec: повторяет только FAILED, сохраняет job_id и монотонный attempt, добавляет новый бюджет и audit. Replay READY — no-op. upgrade UUID --version 2 требует строго возрастающую версию и атомарно создаёт новый job/outbox.

Staging удаляется после безопасной публикации READY; dispatcher очищает остаток при crash до удаления/ack. FAILED staging хранится 24h для явного replay, затем очищается с staging_expired; replay после истечения retention отклоняется. Сверка orphan выполняется после того же grace. Активные upload/worker держат shared advisory lock 741204, cleanup — exclusive try-lock; используется повторная проверка ссылок БД. Активные/свежие и опубликованные объекты не удаляются по возрасту. Очистка старой попытки проверяет версию перед снятием staging-ссылки, поэтому не удаляет исходник новой версии.

Из lab4 сохранены Argon2, Bearer-сессии PostgreSQL, ACL, атомарная идемпотентность сообщений и keyset cursor. История упорядочена по (created_at,id); snapshot между HTTP-запросами нет. При несинхронных часах конкурентная вставка раньше cursor может не попасть в текущий обход. Подтверждённые записи читаются из основной БД через любую API.

Настройки .env.example — логические роли: DATABASE_URL_FILE соответствует postgres_* Docker secrets; S3 credentials — файлам secrets; BROKER_URL_FILE — внутреннему broker:6379 без публичного порта. SESSION_STORE фактически PostgreSQL. WORKER_CONCURRENCY задаёт число worker-реплик, JOB_MAX_ATTEMPTS — бюджет новых jobs/replay, JOB_TIMEOUT_SECONDS=60, JOB_LEASE_SECONDS=75, STAGING_RETENTION_SECONDS=86400, MAX_PENDING_JOBS=100. Admission сериализуется advisory lock 741205: одновременные API не превышают бюджет. Readiness критичны PostgreSQL/S3, broker/worker восстанавливаются через outbox.

Роль Service / версия Устойчивое состояние / проверка
API ×2 Java 21, Spring Boot 4.1.1; Dockerfile/Gradle Wrapper 9.3.0 PostgreSQL/S3, собственных volumes нет; /health/ready
Метаданные db, postgres:16-alpine pgdata; pg_isready
Cache redis, redis:7.4-alpine redisdata; PING; сессии остаются в PostgreSQL
Broker broker, redis:7.4-alpine brokerdata, AOF always; PING
S3 minio, pgsty/silo (MinIO technology), digest в Compose minio-data; /minio/health/ready; app credentials ограничены bucket
Worker ×2 Python 3.12.12, Pillow 12.0.0 Нет локальных оригиналов; terminal jobs/lease контролируются в БД
Outbox dispatcher, тот же Python image processing_outbox в PostgreSQL, одна реплика; SKIP LOCKED поддерживает конкуренцию
LB lb, nginx:1.27-alpine Только опубликованный loopback HTTP порт; upstream api:8080

У API лимиты CPU=1/RAM=512MiB/Xmx320m на реплику, у worker CPU=1/RAM=1GiB, у dispatcher CPU=0.5/RAM=256MiB. Docker VM: 8 CPU, около 7.65GiB RAM; точные значения и image IDs — environment.json. Secrets передаются файлами; административные S3 credentials доступны только bootstrap, не API/worker.

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

Правила хранения: evidence/README.md. Методики: tests/README.md. Фактический stdout сохраняется без токенов, credentials и содержимого сообщений.

Полный повторный прогон выполняется scripts/run_tests.ps1: все исполняемые сценарии tests, оба режима resilience, 30-секундная нагрузка, Java-тесты и OpenAPI. Общий результат: test-suite.txt. client.py, image_probe.py, pipeline_support.py используются как библиотеки сценариев.

Первый общий прогон остановился на предусловии failover: сразу после restart через LB наблюдалась одна API, поэтому остановка реплики ещё не выполнялась. Исходный результат, журнал первого прогона. Оркестратор исправлен: после persistence он ждёт две healthy API и ответы с двумя разными instance ID через LB. Публичный тест не менялся; результаты полного повторного прогона находятся в основном журнале.

Единый стиль собственной реализации проверяется style.py: Java AOSP/google-java-format 1.28.0 и Python Black 25.9.0. Все шесть API-интерфейсов документированы Javadoc; HTTP-статусы и валидация находятся в интерфейсах. Контроллеры содержат одну final service-зависимость, @RequiredArgsConstructor и один вызов сервиса на операцию; дополнительные прокси-сервисы для переноса ResponseEntity не создавались. Для скачивания сервис формирует динамические заголовки. Результат проверки, полная OpenAPI-валидация, целостность публичного задания и отсутствие локальных паролей.

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Сборка/модульные тесты gradlew.bat test; docker compose build Java и контейнеры собираются из исходников Java, Docker
Публичный smoke py tests/smoke.py 202 queued → ready; checksum original; реальный JPEG thumbnail 256×160 smoke
ACL/MIME/filename/размер/повреждение pipeline_core.py Пользовательские ошибки 400/404/413/415, без ложного READY core
queued доступен сообщению, content=409 pipeline_core.py Worker остановлен, API не делает resize core
Crop/WebP, EXIF, alpha, без увеличения pipeline_core.py Геометрия, MIME, checksum и реальные байты вариантов core
Несколько API / конкурентные запросы pipeline_core.py 24 повтора через 2 instance ID, один Message core
Durable staging/outbox/broker pipeline_faults.py API/publisher/broker restart, те же принятые jobs становятся ready faults
Дубль, reorder, crash до/после effects/COMMIT/ack pipeline_faults.py Один manifest и один набор S3 keys на версию faults, времена
Lease/timeout и stale worker pipeline_faults.py Работа восстановлена, устаревшая публикация отклонена faults
Retry/DLQ/replay pipeline_faults.py 3 попытки в ускоренном профиле; FAILED; явный replay; READY replay no-op faults
Версия 2 раньше старой job pipeline_faults.py Старый worker/доставка v1 не меняют manifest v2 faults
Backpressure двух API и восстановление pipeline_faults.py Бюджет 6 в профиле: 6 принятых/4 отклонённых из 10, принятые обработаны backpressure
Нет потери подтверждённых задач pipeline_faults.py Все принятые ID имеют текущую job/outbox и конечный статус ledger
Самостоятельный pixel guard worker, private bucket, retention pipeline_retention.py 49 млн пикселей → FAILED; anonymous S3 → 403; истёкший staging удалён, fresh/referenced сохранены retention
Незавершённая доставка без dispatcher pipeline_ack_guard.py Истёкший worker не ack-ает текущую незавершённую попытку; pending/index сохранены; затем attempt 2 даёт один результат ACK guard, инварианты
Unicode filename на границе pipeline_filename.py 255 ASCII/emoji принимаются, 256 emoji отклоняются; content проходит через LB filename
Межоперационные окна Message / content pipeline_boundaries.py FOR SHARE удерживает статус до COMMIT; download ждёт cleanup fence и освобождает его boundaries
Последнее место истории между двумя API pipeline_history_capacity.py После seed limit−1 десять разных одновременных POST дают один 201 и девять 413; COUNT и INSERT защищены блокировкой строки Chat до COMMIT history capacity
Гибель API между S3 PUT и COMMIT pipeline_upload_crash.py SIGKILL API: незавершённая транзакция откатывается, 202 не подтверждён, staging остаётся unreferenced; прежняя сессия работает после восстановления upload crash
Нагрузка сообщений load.py --duration 30 --concurrency 4 Closed-loop успешные ответы, ошибки и квантили отдельно; не максимум производительности load, stdout
Сохранность всего стенда resilience.py --mode persistence Старая сессия, сообщения и original после restart всех stores persistence, до, после
Failover API resilience.py --mode failover Обслужившая API действительно остановлена, другая читает original failover, до, после

Эксперименты и отказы

Гипотеза: versioned content-addressed объекты и fencing при атомарной публикации результата сохраняют один наблюдаемый эффект несмотря на at-least-once доставку и живого устаревшего worker. Инварианты: 202 имеет durable source/job/outbox; READY имеет original и ровно три варианта текущей версии; старый token/version не меняет новый manifest; повтор READY не тратит попытку; accepted ID не исчезает из реестра.

Fault-injection управляется только оператором через БД и включается отдельным compose.test.yaml. На production по умолчанию отключён. В профиле: 3 попытки, lease=8s, timeout=25s, очередь=6; намеренно короткий lease позволяет доказать работу fencing при ещё живом старом процессе. В production lease=75s больше timeout=60s. Стенд и API остаются с двумя репликами.

Методика — последовательные сценарии pipeline_faults.py. Настоящие PostgreSQL, S3 и Redis, не моки. Publisher и worker аварийно завершаются в контрольных точках; broker перезапускается с volume. Для stale версии worker задерживается после S3 writes, оператор публикует v2, затем доставляются v1/v2 в обратном порядке. Ledger проверяет все 202. При upgrade старая job явно становится SUPERSEDED; исходник и подтверждённое вложение сохраняются, завершается текущая версия. Дополнительный burst — 10 одновременных upload PNG 800×600, ограничение 6; после снятия отказа принятые работы доходят до READY. Это closed-loop опыт, не измерение максимального throughput.

Hardware/версии/лимиты: environment.json; SHA исходников; schema jobs; ресурсы. RSS/CPU samples — docker stats. Дискретные samples могут пропустить краткий пик. Времена сценариев включают Docker CLI/startup и polling; это не чистая latency обработки. Polling завершений burst последовательно завышает ранние времена. Квантили наблюдаемых верхних оценок времени до ready для шести принятых jobs вычисляются из последнего прогона в drain-summary. Они включают Docker startup и последовательный polling, не являются SLA. Максимальный throughput pipeline и полноценные p50/p95/p99 на длинном стационарном потоке не заявляются: выбран fault-injection трек, а не исследование очереди под перегрузкой.

Воздействие Ожидаем Наблюдаем Потеря данных / восстановление
COMMIT до publish, publisher crash outbox сохраняет намерение Фактический stdout faults Те же job_id, без ручного создания новой job
Publish до отметки outbox повторная доставка допустима Один конечный эффект ACK после устойчивого результата
Worker crash до/после S3 lease восстанавливает работу Ограниченная новая попытка S3 keys не размножаются
COMMIT до ack redelivery READY — no-op Одна попытка публикации READY Результат не откатывается
Старый worker/версия SQL fencing и разные version prefixes Manifest v2 неизменен Старые orphan bytes чистятся после grace
Broker/API restart volumes и outbox сохраняют задачи Те же 202 становятся ready Время — в JSON сценариев

At-least-once плюс идемпотентный эффект не означает exactly-once доставку: сообщения и выполнение попыток повторяются; единственна атомарно опубликованная версия результата.

Ограничения и следующие шаги

Если соединение потеряно после COMMIT до HTTP-ответа, исход запроса для клиента неопределён: сохранённое вложение и job остаются устойчивыми. Upload не принимает Idempotency-Key и не обещает отсутствие второго вложения при повторной загрузке; идемпотентный эффект pipeline относится к одной job и её версии. Отдельный SIGKILL-тест фиксирует точку именно до COMMIT.

Стенд учебный и локальный, без HA PostgreSQL/MinIO/LB/host. Две worker-реплики не заменяют HA хранилищ. Произвольный внешний оператор может удалить bytes; система не восстанавливает удалённый источник. Replay после истечения retention не создаёт новый исходник. Версии увеличиваются только оператором, HTTP pipeline-management API не добавлялся. Старые опубликованные manifests сохраняются для аудита; их compaction потребует отдельной политики.

Доставка JSON содержит только служебные IDs, но broker доступен внутренним доверенным сервисам без TLS; для удалённого production нужна отдельная модель доступа. Файлы ≤10MiB читаются ограниченным буфером API; это ограниченная RAM, не constant-memory pipeline. API admission-lock может снижать throughput. Cleanup использует try-lock и может откладываться при постоянных передачах; retention задаёт минимальный grace, не точное время удаления. Первый функциональный fault-прогон прошёл, но сборщик RSS имел ошибку Go template; после исправления выполнен второй полный прогон с обязательной проверкой наличия samples. Эксперимент локальный и ограничен описанными точками, не доказывает отсутствие всех возможных отказов. Изменения не отправлены в remote и PR не создан.