Files
mtusi2026lab5/REPORT.md
T

22 KiB
Raw Blame History

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

  • Автор: Меркулова М. А., БВТ2303.
  • Целевая оценка: 4 (уровни 3 и 4). Треки оценки 5 не заявляются.
  • Ветка: solution/BVT2303-Merkulova, создана от main skeleton 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 и prefixes staging/, 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

  1. Проверяются доступ, имя, bytes (до 10 MiB), PNG/JPEG, пиксели (до 40 млн) и полная декодируемость.
  2. Запись о начатой загрузке фиксируется в PostgreSQL. Под общей с cleanup блокировкой оригинал записывается в приватный MinIO prefix staging/. Это сетевой S3 PUT, а не ephemeral disk и не завершение фоновой работы.
  3. Одной PostgreSQL-транзакцией сохраняются attachment queued, job и outbox; удаляется upload intent.
  4. Только после COMMIT клиент получает 202 со снимком queued, variants=[], error_code=null.
  5. 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 не выполнялся.

Источники