Files
mtusi2026lab5/REPORT.md
T
2026-11-21 11:31:08 +03:00

226 lines
18 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
- Автор, группа: Журавлев Алексей, БПИ2301.
- Целевая оценка: 5; трек 2 — доказанная идемпотентность pipeline.
- Брокер: Redis 7.4.2 Streams с AOF `everysec`, consumer group и at-least-once delivery.
- Источники и помощь ИИ: материалы курса, контракты lab4/lab5, Pillow/boto3/psycopg/redis; использована помощь ИИ при проверке.
## Запуск из чистого clone
Проверено на Windows 11, Docker Engine 29.8.2, Docker Compose v5.5.1,
Python 3.14.6 на хосте; контейнеры используют Python 3.12.11,
PostgreSQL 16.8, Redis 7.4.2, Nginx 1.27.5 и MinIO с закреплённым
digest.
```powershell
.\scripts\init-local-secrets.ps1
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
py -3 -X utf8 scripts\check_contract.py
py -3 -X utf8 scripts\validate_openapi.py
py -3 -X utf8 tests\smoke.py --base-url http://localhost:8080
```
Для остановки без удаления данных: `docker compose --env-file .env down`.
Для намеренного сброса учебного стенда: `docker compose --env-file .env down -v`.
Приложение использует две реплики API, один worker, ограниченный prefetch
(`BROKER_PREFETCH=1`) и ограничение concurrency (`WORKER_CONCURRENCY=2`).
Тестовый стенд запускался в Docker Engine 29.8.2/Docker Compose v5.5.1 на
Windows 11. Аппаратные лимиты конкретного Docker-host не фиксировались,
поэтому throughput и RSS не являются результатами выбранного трека 2.
### Порядок сохранности и границы подтверждения
```text
HTTP upload
-> streaming staging в S3
-> одна PostgreSQL-транзакция: attachment queued + job queued + outbox
-> HTTP 202
-> polling GET /attachments/{id} или message metadata
```
Kafka-style publisher confirm для Redis отсутствует в форме дополнительного
ack: Redis AOF с volume сохраняет Stream, а запись outbox подтверждается в
PostgreSQL отдельно. Ответ 202 означает не готовность изображения, а только
устойчивую регистрацию staging + метаданных + job/outbox. Если API останавливается
после 202, Redis-публикация и обработка продолжаются при сохранённых volumes.
Outbox publisher выдаёт Redis `XADD`, а обработку считает опубликованной только
после записи `published_at` в PostgreSQL.
Семантика ACK разделена:
- ACK consumer означает, что worker добился устойчивого результата или
убедился, что результат уже завершён/устаревшую job надо игнорировать;
- подтверждение записи Stream означает только принятие broker-сообщения;
- `ready` в PostgreSQL означает наличие original и всех трёх обязательных
вариантов для целевого pipeline.
## Реализация по уровням
| Уровень | Реализованный минимум | Как проверено |
| --- | --- | --- |
| 3 | Отдельный worker и Redis Streams, `202 queued`, staging, states, оригинал, thumbnail, ограниченные retries и failed | Public smoke, stop/start worker, сохранение зависшей/принятой job |
| 4 | Crop, optimized WebP, лимиты входа, outbox, replay, backoff+jitter, lease/XAUTOCLAIM, staging retention/cleanup, лимит prefetch/concurrency | `check_contract`, `validate_openapi`, fault injection и stop/start сценарии |
| 5, трек 2 | versioned pipeline, детерминированные effect keys, crash/recovery и stale-job guard | Автоматический сценарий `test-pipeline-faults` и audit replay |
Конфигурация уровня:
- retries: `JOB_MAX_ATTEMPTS=5`;
- lease: `JOB_TIMEOUT_SECONDS=60`, crash-тест использует 5 секунд;
- prefetch: `BROKER_PREFETCH=1`;
- worker concurrency: `WORKER_CONCURRENCY=2`;
- backoff: `2^(attempt-1)` секунд плюс детерминированный jitter до 1 секунды,
максимум 300 секунд;
- limits upload: `MAX_UPLOAD_BYTES=10485760`,
`MAX_IMAGE_PIXELS=40000000`;
- JPEG: quality 88; WebP: quality 86;
- временный staging key: `staging/{attachment_id}`;
- внутренний original key: `objects/{attachment_id}` или контрактный
`object_key` публичного результата;
- variant keys:
`objects/{attachment_id}/thumbnail`,
`objects/{attachment_id}/crop`,
`objects/{attachment_id}/optimized`.
Размеры и контент: `thumbnail` сохраняет пропорции в bounding box 256×256,
`crop` — 128×128 с фиксированным crop по центру, `optimized` — WebP с теми же
размерами оригинала или исходный размер после валидации/ограничений. EXIF
Pillow не переносит при пересохранении.
## Архитектура и перенос из lab4
Перенесены API, авторизация, PostgreSQL/Redis-сессии, сообщения и
идемпотентность, MinIO, приватный bucket, Nginx, миграции, Dockerfile,
reconcile и restart/failover hooks из lab4. Переход upload: `201 ready`
заменён на `202 queued`.
```text
API x2 -> S3 staging + PostgreSQL attachment/job/outbox
-> Redis Stream -> worker
-> S3 objects/{attachment_id}/... -> PostgreSQL ready
```
До ответа 202 API потоково принимает PNG/JPEG в приватный S3-prefix
`staging/`, а одной транзакцией сохраняет метаданные, job и outbox.
Worker публикует только UUID и служебные поля, получает staging по данным
PostgreSQL, сохраняет original, thumbnail 256x256, crop 128x128 и
optimized WebP, затем фиксирует `ready`. Качество JPEG — 88, WebP — 86;
Pillow удаляет EXIF при пересохранении. Оригинал не изменяется.
Повторная доставка использует ключ эффекта
`(attachment_id, pipeline_version, variant)` и детерминированные S3 keys.
Lease, ограничение 5 попыток, exponential backoff с jitter и
`retry_exhausted` предотвращают бесконечные повторы. Старый
`pipeline_version` не может перезаписать новый. Ошибка после S3 side effect
без ACK безопасно повторяет те же ключи; готовая job становится no-op.
Операторский replay выполняется только для `failed` и атомарно повышает
`pipeline_version`, создаёт новую job/outbox и audit-запись:
```powershell
docker compose exec -T worker python scripts/replay_attachment.py ATTACHMENT_ID
```
## Доказательства
| Критерий | Команда/сценарий | Результат |
| --- | --- | --- |
| Контракт | `py -3 -X utf8 scripts\check_contract.py` | PASS |
| OpenAPI/JSON Schema | `py -3 -X utf8 scripts\validate_openapi.py` | PASS |
| Public smoke | `py -3 -X utf8 tests\smoke.py --base-url http://localhost:8080` | PASS: users, sessions, chat, messages, 202 upload, original и реальный JPEG thumbnail |
| Worker recovery | `docker compose stop worker`; запустить smoke; через 5 s `docker compose start worker` | PASS: принятая queued job завершилась ready |
| Fault injection track 2 | `make test-pipeline-faults` на чистом Compose-проекте | PASS: crash после side effect восстановлен lease/re-delivery, один логический результат; [pipeline-faults.json](./evidence/pipeline-faults.json) |
| Durable broker | Redis AOF + named `redis_data` volume; остановка/перезапуск стенда без `-v` | Redis и Stream сохраняются volume; отдельный перезапуск всех хранилищ не сохранён как артефакт |
| Level 4 variants | smoke + API download `thumbnail`, `crop`, `optimized` | PASS: три variant names и deterministic keys |
| Outbox recovery | Таблица `attachment_outbox`, publisher loop и Redis Stream | Реализовано; ручная инъекция COMMIT/publish не сохранена отдельным артефактом |
| Replay/failed | `ATTACHMENT_ID=<id> make replay-attachment` | Реализован audit и повышение pipeline version; успешный failed → ready replay-прогон пока не сохранён |
### Окна отказа и наблюдаемая реакция
| Окно отказа | Защита в реализации | Результат |
| --- | --- | --- |
| staging до commit attachment/job/outbox | одна PostgreSQL-транзакция после успешной записи staging; orphan staging не считается принятой job | 202 не возвращается до успешного commit |
| COMMIT PostgreSQL до Redis publish | persistent `attachment_outbox` с `published_at` и повторный publisher loop | Intent восстанавливается существующим publisher loop |
| Redis publish до ACK worker | Redis consumer group, ACK после устойчивого effect/ready или безопасного no-op | Повторная доставка остаётся at-least-once |
| запись S3 до commit результата | детерминированные effect keys и проверка pipeline version | Повтор завершает тот же эффект без второй логической записи |
| COMMIT result до ACK broker | Redis сообщение остаётся pending до `XACK` | `XAUTOCLAIM`/повторное чтение восстанавливает обработку |
| зависший/мёртвый worker | lease/deadline и `XAUTOCLAIM` после idle timeout | processing job становится доступна другому worker |
Для crash-теста фактическое падение моделируется `os._exit(42)`. Тест
останавливает обычный worker, загружает fixture, запускает fault-worker в режиме
`after-side-effect`, прекращает его после fault, запускает recovery-worker с тем
же Stream и consumer group и проверяет готовое attachment. Артефакт:
[pipeline-faults.json](./evidence/pipeline-faults.json).
## Трек 2: методика и результаты
Гипотеза: при дублировании, reorder и падении worker до/после side effect
каждый attachment завершится не более чем одним логическим набором
вариантов, а более новая версия pipeline не будет перезаписана старой.
Методика: Redis consumer group доставляет одно сообщение повторно после
истечения lease; fault injection задаётся `FAULT_INJECTION` значениями
`before-side-effect`, `after-original`, `after-side-effect`. Все оригинал и
варианты используют детерминированные keys, а запись `ready` выполняется
только после успешной фиксации всех объектов. При повторе проверяется
состояние PostgreSQL и версия job; старый pipeline ACK-ается без side effect.
В реальном стенде остановка worker во время public smoke дала 202 до
запуска worker и PASS после восстановления.
Инварианты:
1. подтверждённая 202 job имеет staging и durable outbox;
2. `ready` означает наличие original и всех трёх обещанных вариантов;
3. повтор не создаёт новый attachment или новый вариант;
4. устаревшая версия не переводит новый результат обратно в processing;
5. доставка не exactly-once: Redis может доставить сообщение повторно,
exactly-once достигается только на уровне идемпотентного эффекта.
Матрица fault-инъекций:
| Событие | Поведение реализации | Автоматический proof |
| --- | --- | --- |
| crash до side effect | `before-side-effect` вызывает `os._exit(42)` до чтения staging; восстановленный worker повторно выполняет job | поддержано кодом; не включено в сохранённый JSON |
| crash после original | `after-original` вызывает crash после записи original, но до variants; повтор использует те же keys и дорабатывает pipeline | поддержано кодом; не включено в сохранённый JSON |
| crash после всех S3 effects до ready | `after-side-effect` вызывает crash после записи всех variants; повтор проверяет версию и фиксирует ready | PASS в `test-pipeline-faults` |
| duplicate delivery | повторно обработанная ready/processing job проверяется по attachment/job state и effect keys | детерминированные keys предотвращают второй набор |
| reorder старой и новой job | новая `pipeline_version` сохраняется в attachment и job; поле старой job меньше или несовместимо, поэтому старый job ACK-ается без effect | guard реализован; отдельный два-worker сценарий не сохранён |
| replay failed | replay разрешён только для `failed`, создаёт новую job/outbox и audit, новый pipeline version; готовая или queued job replay не принимает | script реализован; failed → ready proof не сохранён |
Автоматический сценарий запускается командой
`make test-pipeline-faults`: он останавливает обычный worker, загружает
fixture, запускает fault-worker с `after-side-effect`, заменяет его
recovery-worker с коротким lease и сохраняет обезличенный summary в
`evidence/pipeline-faults.json`. Проверка на чистом Compose-проекте завершилась
`PASS`: `ready`, ровно `thumbnail/crop/optimized`, потеря подтверждённой
задачи отсутствует.
Ограничение: эксперимент одноузловой; потеря PostgreSQL/MinIO volume и
потеря Docker-host не моделируются. RSS/load benchmark не заявляется как
часть выбранного трека.
## Ограничения
PostgreSQL, Redis, MinIO и Nginx одноузловые. Outbox закрывает разрыв
COMMIT→publish, но не делает два хранилища общей транзакцией. Retention
staging очищается после успешной фиксации результата; orphan/missing
объекты обрабатываются существующим reconciliation с grace period.
Независимо от успешного fault-теста решение не заявляется как production
HA: Docker host, PostgreSQL, Redis и MinIO не имеют переносимого отказоустойчивого
cluster-плана; потеря volume или host не покрывается уровнем лабораторной.
Redis запущен с AOF `everysec`, поэтому acknowledgement может потеряться в узком
окне после системного сбоя именно в рамках выбранной политики сохранности.
Не измерялись throughput, p95 queue lag и RSS для трека 1; трек 2 не использует
эти метрики как критерий. Также не публикуются passwords, bearer/session tokens,
S3 credentials, подписанные URL или raw PostgreSQL/Redis dumps. Артефакт
`evidence/pipeline-faults.json` содержит только attachment UUID, fault mode,
status и названия variants.
Дата основного проверочного прогона: 21 ноября 2026. Git commit не указан,
поскольку рабочая папка лабораторной не является git repository. Для
повторяемого PR следует дополнить отчёт точным SHA после инициализации
репозитория и применённого commit.