16 KiB
Отчёт — лабораторная 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 на время прогона остановлены, чтобы порядок событий задавался экспериментом.
Автоматически выполняются:
- crash после claim, но до side effect;
- crash после записи всех S3 объектов, но до commit результата;
- crash после commit результата, но до consumer ACK;
- две дополнительные доставки уже завершённой job;
- постоянная ошибка повреждённого staging и явный replay;
- завершение 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.
Источники и библиотеки
- Redis Streams и consumer groups: https://redis.io/docs/latest/develop/data-types/streams/.
- Redis persistence: https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/.
- PostgreSQL
SKIP LOCKED: https://www.postgresql.org/docs/current/sql-select.html. - MinIO Go SDK: https://github.com/minio/minio-go.
- OpenTelemetry trace context: https://www.w3.org/TR/trace-context/.
- Go-пакеты:
pgx/v5,go-redis/v9,minio-go/v7,deepteams/webp, Prometheus client.