forked from mtusi2026/mtusi2026lab5
226 lines
18 KiB
Markdown
226 lines
18 KiB
Markdown
# Отчёт — лабораторная 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.
|