22 KiB
Отчёт — лабораторная 5
- Автор: Меркулова М. А., БВТ2303.
- Целевая оценка: 4 (уровни 3 и 4). Треки оценки 5 не заявляются.
- Ветка:
solution/BVT2303-Merkulova, создана отmainskeleton lab5. - Основа: собственная реализация lab4; Go API, PostgreSQL, Redis-сессии, две API-реплики, Nginx, приватный MinIO. Контракт, публичные tests, README, COURSE и Makefile текущего skeleton сохранены.
- Commit/PR: заполняется после публикации ветки в fork.
- Помощь ИИ: Codex использован для реализации, анализа отказов, тестов и документации. Код проверялся запуском локального стенда; результаты находятся в
evidence/.
Запуск из чистого clone
Нужны Docker Desktop с Linux containers, Docker Compose 2.22+ и BuildKit, Python 3.9+, make, OpenSSL; интернет для Docker Hub, GitHub/codeload, Go modules и PyPI. Windows: команды выполняются в WSL2 с интеграцией Docker Desktop. Нативный PowerShell не является средой исполнения shell scripts. Локальный Go необязателен.
cd mtusi2026lab5
sh scripts/init-local.sh
# Если localhost:8080 занят другой лабой, изменить APP_PORT в локальном .env.
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
make check
make test
Compose build context application: service:migrate гарантирует сборку Go binary перед worker даже без локального образа. Данные/secrets предыдущей лабораторной не нужны. s3-init настраивает MinIO, migrate применяет SQL; оба после успеха завершаются с кодом 0.
Локально при проверке использовался APP_PORT=18085, поскольку 8080 занят lab4. Для всех команд проверки ниже в этом случае добавляется BASE_URL=http://localhost:18085:
make test BASE_URL=http://localhost:18085
BASE_URL=http://localhost:18085 python3 student-tests/verify_variants.py
BASE_URL=http://localhost:18085 python3 student-tests/verify_pipeline.py
При стандартном порте:
python3 student-tests/verify_variants.py
python3 student-tests/verify_pipeline.py
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
sh scripts/start-api.sh
# Автоматически: StartedAt всех сервисов и целевой отказ каждой API-реплики
python3 student-tests/verify_resilience.py
Failover оставляет выбранную реплику остановленной; после проверки её надо восстановить указанной командой. Pipeline-тест сам восстанавливает остановленные им сервисы. Не запускать одновременно несколько тестов, меняющих состояние контейнеров.
Остановка с сохранением данных:
docker compose --env-file .env down
Намеренное удаление только учебных данных этой лабы, если требуется полный сброс:
docker compose --env-file .env down --volumes
Секреты лежат в secrets/, создаются с закрытыми правами и исключены из Git. .env также не коммитится. Менять ключи при существующем volume без процедуры ротации не следует.
Проверка чистого запуска выполнена в отдельной копии без .env/secrets, с четырьмя новыми volumes и отдельным project name: clean-start.json. При сборке использовался BuildKit cache.
Версии и ресурсы
| Компонент | Версия / лимит |
|---|---|
| API и dispatcher | Go 1.26.8; исходный образ закреплён digest |
| PostgreSQL | 17.6-alpine3.22, 1 CPU / 512 MiB |
| Redis сессий | 8.2.1-alpine3.22, 0.25 CPU / 128 MiB |
| Broker | отдельный Redis 8.2.1-alpine3.22, 0.25 CPU / 128 MiB, AOF appendfsync always, noeviction, отдельный volume |
| MinIO | RELEASE.2025-10-15T17-29-55Z, сборка официальных исходников; checksum архива в infra/Dockerfile.minio, 1 CPU / 512 MiB |
| Worker | Python 3.13.7-slim-bookworm, Pillow 12.0.0 + Go binary, 1 CPU / 1536 MiB |
| API | две реплики, каждая 0.5 CPU / 1536 MiB; один upload slot, tmpfs 20 MiB |
| Dispatcher / cleanup | по 0.25 CPU / 128 MiB |
| Nginx | 1.29.1-alpine3.22, 0.25 CPU / 64 MiB |
Worker subprocess ограничен адресным пространством 1 GiB через RLIMIT_AS; весь контейнер ограничен 1536 MiB. exec.CommandContext завершает subprocess при timeout/cancel. Worker tmpfs 128 MiB, prefetch=1, WORKER_CONCURRENCY=1 по умолчанию (допускается 1–4; увеличение требует проверки ресурсов). API не делает resize/WebP, но полностью декодирует вход для проверки повреждений перед принятием.
Соответствие настроек
Из .env Compose использует внешний APP_PORT, APP_HOST, APP_ENV, TTL сессии и идемпотентности, DB timeout/pool, настройки попыток/worker/retention и grace очистки. Внутренний порт API — 8080, число API-реплик — 2. Адрес MinIO, регион и bucket заданы в compose.yaml; 10 MiB и 40 млн пикселей закреплены в коде. Поля SESSION_STORE, API_REPLICAS, MAX_UPLOAD_BYTES, MAX_IMAGE_PIXELS в примере skeleton служат справочными значениями и не переключают реализацию.
Архитектура
flowchart LR
C[Клиент] --> LB[Nginx]
LB --> A1[API 1]
LB --> A2[API 2]
A1 --> PG[(PostgreSQL)]
A2 --> PG
A1 --> R[(Redis: сессии)]
A2 --> R
A1 --> S[(MinIO: staging, originals, variants)]
A2 --> S
PG --> D[Dispatcher: outbox]
D --> B[(Redis Streams: broker)]
B --> W[Worker + Pillow subprocess]
W --> S
W --> PG
Что изменено относительно lab4
004_async_pipeline.sql: jobs, outbox, lease, попытки, варианты, реестр failed/replay, состояния queued/processing/ready/failed.attachments.go: durable staging вместо немедленного ready,202 queued; метаданные вариантов и скачивание выбранного варианта; content до ready возвращает 409.server.go: queued/processing разрешены в сообщениях, failed запрещён; проверка сессии/участия в чате сохранена.internal/pipeline/pipeline.go: dispatcher, consumer group, XAUTOCLAIM, retry, lease, фиксация результата, retention, replay, точки crash injection.worker/process_image.py: EXIF orientation, белый фон alpha, JPEG thumbnail/crop, WebP optimized.- Compose: отдельные broker/dispatcher/worker, volume брокера, параметры и лимиты.
bootstrap.go: права ограничены bucket и prefixesstaging/,originals/,variants/; root credentials отсутствуют у API/worker/dispatcher/cleanup.cleanup.go: старые неподтверждённые staging uploads удаляются только после grace, принятые jobs защищены.main.go: режимы worker/dispatcher/replay/failed-jobs/fault, чтение конфигурации.restart.sh: перезапускает также broker, dispatcher и worker с сохранением volumes.
Граница 202 и transactional outbox
- Проверяются доступ, имя, bytes (до 10 MiB), PNG/JPEG, пиксели (до 40 млн) и полная декодируемость.
- Запись о начатой загрузке фиксируется в PostgreSQL. Под общей с cleanup блокировкой оригинал записывается в приватный MinIO prefix
staging/. Это сетевой S3 PUT, а не ephemeral disk и не завершение фоновой работы. - Одной PostgreSQL-транзакцией сохраняются attachment queued, job и outbox; удаляется upload intent.
- Только после COMMIT клиент получает
202со снимком queued,variants=[],error_code=null. - Dispatcher читает outbox и выполняет XADD. После положительного ответа брокера отмечает публикацию. Пока работа queued/due или lease истёк, намерение может публиковаться снова (не чаще 5 секунд).
Если API умер после staging до COMMIT — ответа 202 нет, остаток удаляется после grace. Если COMMIT выполнен, а publish не состоялся — outbox остаётся и dispatcher публикует после восстановления. Если publish состоялся, но его отметка потерялась — допустим дубль. API не требует доступного worker или broker для приёма: устойчивый синхронный путь требует PG, Redis sessions и MinIO. Broker/worker отсутствуют в API readiness намеренно; backlog хранится в PG/staging.
Worker, lease и идемпотентность
Redis Stream attachment.jobs.v1, consumer group image-workers; сообщения JSON соответствуют contracts/jobs.schema.json. В них только schema/job/attachment/pipeline/attempt/time, без bytes, storage URL, filename или credentials. Storage key берётся из доверенной БД. job_id стабилен, pipeline_version=1, управляемая попытка берётся из PostgreSQL; повтор доставки не создаёт новый логический job.
Worker получает/восстанавливает сообщение, захватывает PostgreSQL advisory lock по job и в короткой транзакции переводит job/attachment в processing. Lease = JOB_TIMEOUT_SECONDS + 5 секунд, reclaim pending через XAUTOCLAIM после timeout+10 секунд. Dispatcher также повторно публикует expired lease; поэтому зависшая работа восстанавливается даже при потере stream-сообщения. Session advisory lock исключает одновременную обработку одного job; lease token проверяется перед публикацией результата.
Объектные ключи детерминированы:
originals/<attachment_id>— неизменный оригинал;variants/<attachment_id>/v1/thumbnail;variants/<attachment_id>/v1/crop;variants/<attachment_id>/v1/optimized.
После записи всех четырёх объектов одна транзакция устанавливает ready, variants/checksums и завершает job. Ack только после COMMIT результата или устойчивой записи retry/failed. Ready-дубль подтверждается без повторного resize/смены состояния/увеличения attempts. Для единственной consumer group после XACK сообщение удаляется XDEL; durable intent и результат остаются в PostgreSQL. Это at least once с идемпотентным эффектом, а не exactly-once доставка.
Правила изображений
Оригинал возвращается побайтно неизменным. SHA-256/size/type вложения всегда относятся к оригиналу.
- EXIF orientation применяется перед преобразованиями.
- Alpha компонуется на белый фон.
- Thumbnail: JPEG quality=85, fit в 256×256, без увеличения, размеры округляются вниз, минимум 1; 320×200 → 256×160.
- Crop: JPEG quality=85, центрированный квадрат 128×128; маленькие изображения допускают увеличение.
- Optimized: lossy WebP quality=80, method=4, fit в 1280×1280 без увеличения.
- В новых изображениях не сохраняются EXIF/ICC/text metadata. Уменьшение размера каждого исходника не обещается.
Retry, failed registry и replay
JOB_MAX_ATTEMPTS=5 (1–20), JOB_TIMEOUT_SECONDS=60 (1–120). Временные ошибки storage/processing/timeout: задержка 2^(attempt-1) секунд (база ограничена 32 сек) + случайный jitter 0–50%. Изменение next_at и queued фиксируется до ack; dispatcher публикует только наступившую попытку. Повреждённый источник/checksum — постоянная invalid_image, без бесполезных повторов. Исчерпание попыток — failed / retry_exhausted.
Реестр failed — таблица attachment_jobs, видимая оператору через CLI; публичные метаданные содержат только безопасный error_code. Некорректные broker envelopes попадают в attachment.invalid.dlq без содержимого/секретов.
docker compose --env-file .env exec -T dispatcher /messenger failed-jobs
# После устранения причины, с job UUID из реестра:
docker compose --env-file .env exec -T dispatcher /messenger replay <job-uuid>
Replay разрешён только failed, при сохранённом и доступном staging. Он атомарно создаёт audit-запись, возвращает queued, обнуляет бюджет попыток и открывает outbox для той же логической работы. Ready replay отклоняется. После истечения retention и удаления staging replay отклоняется; исходник нужно загрузить заново как новую операцию. CLI не публикуется как HTTP endpoint.
Очистка
Dispatcher удаляет staging после атомарного ready. Для failed staging сохраняется STAGING_RETENTION_SECONDS=86400 после последнего перехода; затем удаляется под блокировкой строки job, совместимой с replay. Processing/queued staging не удаляется. Не принятые uploads без job/метаданных удаляет cleanup после CLEANUP_GRACE_SECONDS=3600 (минимум 120). Свежие и занятые объекты сохраняются. Ошибка удаления не уничтожает запись намерения, следующий проход повторяет очистку.
Совместимость
Сохранены Basic→Bearer, expiry/logout, ACL, keyset pagination, идемпотентность сообщений и две реплики. Семантика пагинации как в lab4: порядок (created_at,id), snapshot между запросами не гарантируется; запись с поздним COMMIT и более ранним ключом может не попасть в уже пройденную страницу. Подтверждённые записи видны новым чтениям через обе реплики.
Доказательства критериев
См. актуальный протокол evidence/lab5-results.md, JSON variants-grade4, pipeline-grade4 и resilience.
| Критерий | Команда / сценарий | Что проверяется |
|---|---|---|
| Публичный минимум lab5 | make check, make test |
202, ready, original, настоящий JPEG thumbnail, предыдущие API |
| Crop/WebP, orientation, alpha | python3 student-tests/verify_variants.py |
Полное Pillow-декодирование ответов, размеры, EXIF, checksum |
| Byte/pixel limits и доступ | тот же тест | Точные 10 MiB через LB, 413/415, outsider 404, приватность S3 |
| Worker отсутствует, задача durable | python3 student-tests/verify_pipeline.py |
queued/409, сообщение с queued, реальные рестарты API/broker и ready после старта worker |
| COMMIT/publish gap | тот же тест | Реальный exit 86 dispatcher до XADD, автоматическое восстановление из outbox |
| Crash S3 до COMMIT/ack | тот же тест | Exit 86 worker после объектов, expired processing, attempts=2, один набор variants |
| COMMIT до ack, redelivery ready | тот же тест | Exit 86 перед ack, явный дубль, неизменный результат и attempts |
| Backoff/bounded retry, failed/replay | тот же тест + go test ./... |
Временная недоступность S3, исчерпание тестового бюджета 2, реестр, audit replay, запрет replay ready |
| Постоянная ошибка | pipeline test | Неверный checksum → invalid_image, одна попытка; replay ранее созданного сообщения сохранён |
| Безопасная очистка staging | pipeline test | Staging удалён после ready; queued переживает рестарт |
| Сохранность всех хранилищ | make test-persistence ACTION_SCRIPT=scripts/restart.sh |
Те же данные/токен/оригинал после перезапуска, StartedAt в evidence |
| Отказ API | make test-failover ACTION_SCRIPT=scripts/stop-one.sh |
Работа через surviving API, оригинал/данные сохранены |
После обработки 40 млн пикселей измеренный memory.peak worker составил 701 313 024 байта (668.82 MiB) при hard limit 1 610 612 736 байт (1536 MiB). Это результат указанного набора тестов, а не максимальная оценка для всех PNG/JPEG.
Сценарии отказов
В pipeline_faults существуют CLI-only одноразовые точки dispatcher_before_publish, dispatcher_after_publish, worker_after_claim, worker_after_objects, worker_before_ack. Тест ставит точку через /messenger fault arm <point>; процесс устойчиво записывает hit и реально завершается os.Exit(86). Политика Compose восстанавливает процесс. Это не симуляция успешного результата. Публичного HTTP управления fault injection нет.
Проверки выполняются на синтетических данных. Нагрузочный трек оценки 5 не заявлен; производительность и production SLA из этих сценариев не выводятся.
Ограничения
- Один Docker-host и одиночные PostgreSQL/MinIO/broker/Nginx: потерю host/volume не покрываем; необходимы резервные копии/репликация для production.
- Durable staging уже находится в S3, worker публикует оригинал в конечный prefix того же MinIO. Это не отдельная физическая система хранения.
- Backlog принятой работы хранится без установленной квоты; нагрузочный backpressure и сравнение concurrency относятся к треку 5 и не заявлены.
- Публикация может создавать дубли; количество обработок ограничено, эффекты защищены. PostgreSQL jobs/outbox/audit сохраняются для диагностики; их архивирование не реализовано.
- Параметры concurrency выше 1 требуют повторной проверки памяти; проверяемая конфигурация — 1.
- Простой HTTP допустим только для локального изолированного стенда. Windows/WSL2 инструкция приведена, отдельный запуск на Windows не выполнялся.
Источники
- Собственная реализация лабораторной 4.
- Redis Streams: consumer groups, pending и ack.
- Redis XAUTOCLAIM.
- Pillow ImageOps: EXIF и crop.
- Pillow форматы JPEG и WebP.
- Официальные исходники MinIO.