From aef85e362add8a86252285b779398a4a7d326bcb Mon Sep 17 00:00:00 2001 From: killoq7 Date: Sat, 21 Nov 2026 11:31:08 +0300 Subject: [PATCH] report fix --- REPORT.md | 115 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 113 insertions(+), 2 deletions(-) diff --git a/REPORT.md b/REPORT.md index fdbbc9f4..783dc0d1 100644 --- a/REPORT.md +++ b/REPORT.md @@ -24,6 +24,70 @@ 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-сессии, сообщения и @@ -67,8 +131,27 @@ docker compose exec -T worker python scripts/replay_attachment.py ATTACHMENT_ID | 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; job/outbox проверяются при старте worker | Объявлено в Compose и проверено запуском | -| Level 4 variants | smoke + API download `thumbnail`, `crop`, `optimized` | deterministic keys, checksums и metadata | +| 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= 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: методика и результаты @@ -94,6 +177,17 @@ docker compose exec -T worker python scripts/replay_attachment.py ATTACHMENT_ID 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`, заменяет его @@ -112,3 +206,20 @@ 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.