32 KiB
Отчёт — лабораторная 5
- Автор, группа: Иванов Данил, БВТ2301 (перенесено из отчёта lab4).
- Целевая оценка: 5, трек 2 — доказанная идемпотентность pipeline.
- Форк: https://gitea.privcloud.tech/landcruiser200/mtusi2026lab5. Основа задания —
276dbdad8a34da4c5b57fbf1879ca169b581d75b; реализация перенесена из lab4cc0ef71. Результаты относятся к рабочему дереву, исходники зафиксированы 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 не создан.