Files
mtusi2026lab5/REPORT.md
T

183 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 5
- Автор: Пластинин Денис, БВТ2303.
- Целевая оценка: 5.
- Выбранный трек: 2, доказанная идемпотентность versioned pipeline.
- Ветка решения: `solution/bvt2303-plastinin`.
## Запуск из чистого clone
Требуются Docker с Compose и Python 3.9+. Все серверные зависимости поднимаются из репозитория. Локальные пароли из `lab5.env.example` предназначены только для изолированного учебного стенда.
```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 секунд.
## Доставка, retry и восстановление
Dispatcher забирает due outbox events через `FOR UPDATE SKIP LOCKED` и lease token. После подтверждённого `XADD` event помечается опубликованным. Сбой после `XADD`, но до этой отметки создаёт допустимый дубль.
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 содержит RPS, status classes, p95 API latency, Go heap, PostgreSQL, Valkey, MinIO, throughput pipeline по результатам, p95 обработки, in-flight jobs, retry/reclaim, outbox publish failures и Redis broker memory/commands.
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, но не заменяет репликацию и резервное копирование. Lease должен быть больше максимального времени обработки; для больших production изображений нужен heartbeat продления lease. Deadline проверяется между стадиями, но библиотечный вызов WebP не прерывается посередине кодирования. 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.