Files

16 KiB
Raw Permalink Blame History

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

  • Автор: Пластинин Денис, БВТ2303.
  • Целевая оценка: 5.
  • Выбранный трек: 2, доказанная идемпотентность versioned pipeline.
  • Ветка решения: solution/bvt2303-plastinin.

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

Требуются Docker с Compose и Python 3.9+. Все серверные зависимости поднимаются из репозитория. Обычные настройки приложения находятся в config/messenger.yaml; .env содержит адреса окружения, локальные credentials и параметры контейнеров.

cp lab5.env.example .env
docker compose config --quiet
docker compose up -d --build --scale api=2 --wait --wait-timeout 180
make test

После запуска доступны:

  • API через Nginx: http://localhost:8080;
  • Swagger UI: http://localhost:8081;
  • Prometheus: http://localhost:9090;
  • Grafana: http://localhost:3000, пользователь admin, пароль берётся из GRAFANA_ADMIN_PASSWORD.

Интеграционные проверки PostgreSQL и Valkey запускаются отдельно:

docker compose --profile tests run --rm --build tests

Эксперимент трека 5 временно останавливает обычные dispatcher и worker, запускает управляемые сбои, затем возвращает процессы в работу:

make test-lab5

Обязательный сценарий с остановленным worker и разрывом commit → publish:

make test-lab5-acceptance

Обычная остановка сохраняет volumes:

docker compose down

Намеренное удаление всех учебных данных:

docker compose down -v

Архитектура

flowchart LR
    Client --> Nginx
    Nginx --> API1[API replica 1]
    Nginx --> API2[API replica 2]
    API1 --> PostgreSQL
    API2 --> PostgreSQL
    API1 --> Valkey[Valkey sessions]
    API2 --> Valkey
    API1 --> S3[(MinIO / S3)]
    API2 --> S3
    PostgreSQL -->|outbox lease| Dispatcher
    Dispatcher -->|XADD| Redis[(Redis Streams + AOF)]
    Redis -->|XREADGROUP| Worker
    Worker --> S3
    Worker -->|lease + result transaction| PostgreSQL
    Worker -->|XACK after commit| Redis

PostgreSQL является источником истины для metadata, состояния job, попытки, lease, версий pipeline, вариантов и outbox. MinIO хранит исходник в staging и готовые объекты. Valkey хранит только сессии. Отдельный Redis используется как durable broker: включены AOF, appendfsync always, volume и политика noeviction.

Temporal не используется. В работе один короткий тип workflow без ожидания внешних событий и компенсаций между множеством сервисов. Transactional outbox, job lease и Redis consumer group закрывают требуемые окна отказа с меньшим числом компонентов. Добавление Temporal потребовало бы Temporal Service и отдельного persistent store, при этом PostgreSQL job/outbox всё равно понадобился бы для атомарной связи с attachment metadata.

Граница ответа 202

API полностью читает и проверяет PNG/JPEG: MIME, фактический формат, размер и число пикселей. Затем создаётся pending metadata, а байты записываются в приватный ключ staging/<attachment_id>/<uuid> в S3. После успешной записи одна транзакция PostgreSQL переводит attachment в queued, создаёт job и outbox event. Только после commit клиент получает 202 Accepted со snapshot состояния queued.

Если запись staging не удалась, 202 не возвращается. Если соединение потеряно после commit, сохранённый outbox остаётся источником восстановления. Бинарные данные, S3 ключи и credentials в Redis не передаются: envelope содержит только schema version, job ID, attachment ID, pipeline version, attempt, время и trace context.

Обработка изображений

Worker повторно проверяет доверенный staging объект и создаёт четыре content-addressed объекта:

Вариант Формат Правило
original исходный PNG/JPEG байты не изменяются
thumbnail JPEG quality 85 fit в 256×256, без увеличения
crop JPEG quality 85 центральный квадрат 128×128, увеличение разрешено
optimized WebP quality 82, method 4 fit в 1280×1280, без увеличения

EXIF orientation применяется к производным вариантам. Прозрачность сводится на белый фон. Повторное кодирование удаляет metadata. Ключ эффекта имеет вид attachments/<id>/pipelines/<version>/<variant>/<sha256>.<ext>, поэтому повтор той же операции записывает тот же объект.

Concurrency и prefetch задаются через worker.concurrency и worker.prefetch. Перед decode worker оценивает память по размеру входа, числу исходных пикселей и производным буферам, затем занимает часть worker.memory_bytes через weighted semaphore. Для разрешённых 40 млн пикселей зарезервировано 704 MiB внутри контейнера с лимитом 1 GiB; несогласованная конфигурация останавливает worker при старте. Одна попытка ограничена 20 секундами при lease 30 секунд. Worker продлевает lease каждые 5 секунд; потеря lease отменяет обработку. Decode и собственные циклы преобразования проверяют context во время работы.

Доставка, retry и восстановление

Dispatcher забирает due outbox events через FOR UPDATE SKIP LOCKED и lease token. После подтверждённого XADD event помечается опубликованным. Сбой после XADD, но до этой отметки создаёт допустимый дубль. Опубликованные события хранятся семь суток и удаляются раз в минуту пакетами до 1000 строк, не задерживая первый dispatch после запуска.

Worker читает consumer group через XREADGROUP. При старте обработки PostgreSQL атомарно проверяет job_id, pipeline_version, attempt, выдаёт lease token и переводит attachment в processing. Результат применяется только при совпадении всех fencing полей и живом lease. XACK выполняется после commit результата. После ACK обработанная запись удаляется из основного stream; pending записи не вытесняются. Failed stream ограничен приблизительно 10 000 записями.

Временная ошибка переводит job обратно в queued, увеличивает attempt и в той же транзакции создаёт новый outbox event. Задержка растёт экспоненциально и получает детерминированный jitter до 25%. Постоянные ошибки (invalid_image, image_too_large, source_missing) и исчерпание пяти попыток переводят attachment в failed. Явный replay выполняется командой:

docker compose run --rm api /app/messenger replay-attachment <attachment-id> <actor> <reason>

Replay допустим только для failed, увеличивает attempt и сохраняет audit record. Повтор ready job становится no-op. XAUTOCLAIM возвращает зависшие Redis deliveries, а PostgreSQL recovery возвращает job с истёкшим lease в очередь. Старый consumer не может подтвердить delivery после передачи новому consumer: Lua script проверяет владельца PEL перед XACK или переносом в failed stream.

Эксперимент трека 5

Гипотеза

At-least-once доставка не создаст второй логический результат, если effect адресуется по (attachment_id, pipeline_version, variant), а публикация metadata защищена attempt и lease token. Старая версия pipeline не сможет перезаписать текущую.

Методика

Go-программа cmd/lab5experiment работает с настоящими PostgreSQL, Redis Streams и MinIO из Compose. Используется PNG 320×200. Обычные worker и dispatcher на время прогона остановлены, чтобы порядок событий задавался экспериментом.

Автоматически выполняются:

  1. crash после claim, но до side effect;
  2. crash после записи всех S3 объектов, но до commit результата;
  3. crash после commit результата, но до consumer ACK;
  4. две дополнительные доставки уже завершённой job;
  5. постоянная ошибка повреждённого staging и явный replay;
  6. завершение pipeline v2, после которого доставляется устаревшая job v1.

Для первых двух сценариев ожидается истечение lease, увеличение attempt и завершение следующей попыткой. В третьем и четвёртом сценариях повтор должен подтвердиться как no-op. Повреждённый staging дважды завершается одинаковым безопасным invalid_image, причём replay увеличивает attempt и проходит только через audit/outbox. После готовой версии v2 поздняя v1 не меняет metadata.

Результат

Raw summaries сохранены в evidence/lab5-idempotency.json и evidence/lab5-resilience.json.

Воздействие До восстановления После восстановления
crash до side effect 0 конечных объектов attempt 2, ready, 4 объекта
crash после side effect 4 объекта, DB ещё processing attempt 2, ready, те же 4 объекта
crash после commit до ACK DB уже ready, 4 объекта attempt 1, повтор no-op, 4 объекта
две duplicate deliveries 4 объекта 4 объекта
permanent failure и replay failed, invalid_image replay attempt 2, снова failed, invalid_image
stale v1 после готовой v2 ready v2 остаётся ready v2, 8 объектов для двух версий

Все пять подтверждённых logical jobs дошли до терминального состояния: четыре ready, одна ожидаемо failed. Инварианты accepted_jobs_reach_terminal_state, duplicate_effect_is_unique и old_pipeline_cannot_replace_new получили true. Прогон занял 6981 ms.

Это не exactly-once доставка: Redis может доставить одно сообщение несколько раз, а dispatcher может повторить XADD. Exactly-once относится только к наблюдаемому эффекту, который достигается идемпотентными ключами и compare-and-set в PostgreSQL.

Мониторинг и CI

Prometheus опрашивает API replicas, worker, dispatcher, PostgreSQL exporter, отдельные exporters Valkey и Redis broker, Nginx и MinIO. Grafana dashboard разделён на блоки API, PostgreSQL, Valkey/Redis, object storage и attachment pipeline. В нём показаны timing основных ручек, CPU, соединения и транзакции PostgreSQL, cache hit/miss, память, доступность worker/dispatcher, throughput, p95 обработки, in-flight jobs, retry/reclaim, outbox backlog, Redis Streams lag, PEL, DLQ и idle consumers.

CI для pull request и main выполняет contract check, OpenAPI validation, formatting, lint, race tests, build, публичный smoke, интеграционные тесты, persistence/failover lab4 и fault injection lab5. Production workflow запускается вручную и требует approval environment перед rolling deployment.

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

Критерий Команда Результат
Публичный API lab5 make test PASS: queued → ready, original и thumbnail проверены
PostgreSQL и Valkey docker compose --profile tests run --rm --build tests оба пакета PASS
Transform go test ./internal/messenger/attachment/transform thumbnail/crop/WebP, EXIF, alpha и лимиты PASS
Redis и outbox go test ./internal/broker/redisstream ./internal/outbox envelope, poison, owner fencing и lost lease PASS
Worker остановлен, outbox gap, restart broker/API make test-lab5-acceptance queued link и 409 до worker; после restart ready, original сохранён
Трек 5 make test-lab5 5/5 jobs terminal, 4 ready, 1 expected failed, все три инварианта true

Ограничения

Один MinIO, PostgreSQL и Redis container не дают высокой доступности самих хранилищ. appendfsync always уменьшает окно потери Redis, но не заменяет репликацию и резервное копирование. Decode и собственные циклы обработки прерываются по deadline; библиотечный вызов WebP обрабатывает ограниченный вариант до 1280×1280 и не прерывается посередине кодирования. Failed stream ограничен, поэтому перед достижением retention limit записи нужно выгружать во внешнее долговременное хранилище. Staging у failed сохраняется для явного replay; его окончательное удаление остаётся отдельной операторской retention policy.

Источники и библиотеки