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

18 KiB
Raw Permalink Blame History

Отчёт — лабораторная 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.

.\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.

Порядок сохранности и границы подтверждения

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.

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-запись:

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
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.

Трек 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.