forked from mtusi2026/mtusi2026lab5
183 lines
16 KiB
Markdown
183 lines
16 KiB
Markdown
# Отчёт — лабораторная 5
|
||
|
||
- Автор: Пластинин Денис, БВТ2303.
|
||
- Целевая оценка: 5.
|
||
- Выбранный трек: 2, доказанная идемпотентность versioned pipeline.
|
||
- Ветка решения: `solution/bvt2303-plastinin`.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Требуются Docker с Compose и Python 3.9+. Все серверные зависимости поднимаются из репозитория. Обычные настройки приложения находятся в `config/messenger.yaml`; `.env` содержит адреса окружения, локальные credentials и параметры контейнеров.
|
||
|
||
```sh
|
||
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 запускаются отдельно:
|
||
|
||
```sh
|
||
docker compose --profile tests run --rm --build tests
|
||
```
|
||
|
||
Эксперимент трека 5 временно останавливает обычные dispatcher и worker, запускает управляемые сбои, затем возвращает процессы в работу:
|
||
|
||
```sh
|
||
make test-lab5
|
||
```
|
||
|
||
Обязательный сценарий с остановленным worker и разрывом commit → publish:
|
||
|
||
```sh
|
||
make test-lab5-acceptance
|
||
```
|
||
|
||
Обычная остановка сохраняет volumes:
|
||
|
||
```sh
|
||
docker compose down
|
||
```
|
||
|
||
Намеренное удаление всех учебных данных:
|
||
|
||
```sh
|
||
docker compose down -v
|
||
```
|
||
|
||
## Архитектура
|
||
|
||
```mermaid
|
||
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 выполняется командой:
|
||
|
||
```sh
|
||
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.
|
||
|
||
## Источники и библиотеки
|
||
|
||
- 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.
|