forked from mtusi2026/mtusi2026lab6
258 lines
37 KiB
Markdown
258 lines
37 KiB
Markdown
# Отчёт — лабораторная 5
|
||
|
||
- Автор, группа: Попов Константин Дмитриевич, группа БВТ2303
|
||
- Целевая оценка: **4**; трек 5 не заявляется
|
||
- Commit/PR: TODO после публикации
|
||
- Использованные источники, библиотеки и помощь ИИ: Python 3.12, FastAPI 0.115.6, Uvicorn 0.34.0, Pydantic 2.10.4, psycopg 3.2.3 + psycopg-pool 3.2.4, **redis-py 5.2.1 (Redis Streams)**, argon2-cffi 23.1.0, boto3 1.35.99, **Pillow 11.1.0 (JPEG/WebP, ImageOps.exif_transpose)**; PostgreSQL 16.4, Redis 7.4.1 (кэш сессий **и отдельный брокер**), HAProxy 2.8.30, SeaweedFS 4.50. Документация: Redis Streams (XADD, XREADGROUP, XACK, XAUTOCLAIM, XPENDING, XTRIM MINID), Redis persistence (AOF, `appendfsync always`), RabbitMQ reliability/confirms (различие publisher confirm и consumer ack), шаблон transactional outbox, AWS Architecture Blog «Exponential Backoff And Jitter», Pillow (draft, reduce/reducing_gap, сохранение JPEG/WebP), Python `multiprocessing` (forkserver) и `resource` (RLIMIT_AS/RLIMIT_CPU). Помощь ИИ (Claude) — при проектировании outbox/аренд/fencing, написании worker, тестов отказов и отчёта.
|
||
|
||
Минимум lab4 перенесён целиком (балансировщик, ≥2 реплики, сессии, идемпотентность, приватный S3, проверки изображений, сборщик БД↔S3). Единственное объявленное изменение API: `POST /chats/{id}/attachments` отвечает **202 queued** вместо 201 ready.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
**Версии.** API и worker — один образ из `Dockerfile` (`python:3.12.7-slim-bookworm`); `postgres:16.4-alpine`; `redis:7.4.1-alpine` (два сервиса: `redis` — кэш сессий, `broker` — очередь); `haproxy:2.8.30-alpine`; `chrislusf/seaweedfs:4.50`. Нужны Docker Engine/Desktop с Compose v2 и Python 3.9+ на хосте (`scripts/ops.py` и тесты — только стандартная библиотека). Оркестрация — **Compose** (Swarm не используется).
|
||
|
||
```sh
|
||
$env:PYTHONUTF8 = "1"
|
||
# 1. Секреты (один раз; secrets/ в .gitignore, значения не печатаются) и .env
|
||
python scripts/init_secrets.py # lab5 добавляет secrets/broker_password и secrets/broker_url
|
||
cp .env.example .env # Windows: copy .env.example .env
|
||
|
||
# 2. Сборка и запуск:
|
||
# postgres, redis, broker -> migrate (001..005); s3 -> s3-init (bucket) -> api x2 + worker -> lb
|
||
docker compose --env-file .env config --quiet
|
||
docker compose --env-file .env up -d --build
|
||
|
||
# 3. Готовность: 2 реплики healthy и UP в HAProxy, S3 реально пишет/читает, worker healthy
|
||
python scripts/ops.py wait
|
||
python scripts/ops.py wait-s3
|
||
python scripts/ops.py worker-start # идемпотентно: дождаться healthy worker
|
||
python scripts/ops.py ps
|
||
```
|
||
|
||
Всё то же одной командой: `make up` (= init_secrets + config + up --build + ожидания). Прогрев после первой сборки ~30–40 с.
|
||
|
||
```sh
|
||
# Публичные проверки
|
||
make check # офлайн, без сервера
|
||
make test # smoke lab5: 202 -> ready -> thumbnail 256x160
|
||
python tests/resilience.py --mode persistence --action-script scripts/restart.sh # Windows: scripts\restart.cmd
|
||
python tests/resilience.py --mode failover --action-script scripts/stop-one.sh # Windows: scripts\stop-one.cmd
|
||
python scripts/ops.py restore
|
||
|
||
# Собственные проверки lab5
|
||
make test-pipeline # варианты по фактическим байтам (7 тестов)
|
||
make test-worker-outage # сценарий защиты уровня 3 (останавливает/запускает worker, рестарт API и broker)
|
||
make test-pipeline-faults # 10 внедрённых отказов уровня 4 (~2–3 мин; worker временно пересоздаётся)
|
||
python student-tests/run_all.py --base-url http://localhost:8080 # lab2-4 (+ test_pipeline.py)
|
||
|
||
# Всё сразу с записью в evidence/ (~20 мин; только на учебном стенде)
|
||
python scripts/collect_evidence.py # или --quick (~10 мин)
|
||
```
|
||
|
||
**Операторские команды очереди** (выполняются в one-off контейнере образа worker, секреты не печатаются):
|
||
|
||
```sh
|
||
python scripts/ops.py jobs stats # задания по статусам, outbox, DLQ, длина/pending/lag потока
|
||
python scripts/ops.py jobs failed # реестр dead_letters
|
||
python scripts/ops.py jobs show <attachment_id> # задание + журнал событий (job_events)
|
||
python scripts/ops.py jobs replay <attachment_id> # явный replay failed (make replay ID=...)
|
||
python scripts/ops.py jobs replay --all-failed --error-code retry_exhausted --dry-run
|
||
python scripts/ops.py worker-stop | worker-start | worker-kill | api-restart | broker-restart
|
||
python scripts/ops.py reconcile [--apply] # сверка БД <-> S3 (staging/, final/, originals/)
|
||
```
|
||
|
||
**Остановка.** Безопасная (volumes `pgdata`, `s3data`, `brokerdata` сохраняются): `make down` или `docker compose --env-file .env --profile ttl --profile faults down`. **Намеренное удаление всех учебных данных:** `docker compose --env-file .env --profile ttl --profile faults down -v` (удаляет БД, бакет и очередь безвозвратно).
|
||
|
||
## Архитектура и решения
|
||
|
||
```
|
||
клиент ──HTTP──> HAProxy ──> API x2 ──[1] INSERT pending ─────────────────────────> PostgreSQL
|
||
├──[2] PUT staging/<random> (Content-MD5) ───────> S3 (SeaweedFS)
|
||
├──[3] COMMIT: queued + attachment_jobs + job_outbox ──> PostgreSQL
|
||
│ └─> 202 queued
|
||
└──[4] после ответа: relay XADD (fsync) ─────────> broker (Redis Streams)
|
||
│ XREADGROUP (prefetch 1)
|
||
worker (WORKER_CONCURRENCY consumer'ов) <───────────────────────────────────────────────┘
|
||
claim: аренда в PostgreSQL (lease_token, lease_until)
|
||
читает staging (ключ из БД) -> SHA-256 -> PUT final/<id>/original
|
||
подпроцесс (RLIMIT_AS, timeout): thumbnail/crop/optimized -> PUT final/<id>/p1/<variant>
|
||
COMMIT (fenced по lease_token): attachment_variants + state=ready ──> PostgreSQL
|
||
XACK ──> broker; DELETE staging (иначе — сборщик)
|
||
sweeper outbox + сборщик просроченных аренд: в каждой реплике API и в worker
|
||
```
|
||
|
||
**Источник истины** — PostgreSQL: состояние вложения, задание, outbox, результаты, журнал. S3 хранит байты (staging/ и final/), брокер — только транспорт уведомлений (может быть пересоздан из outbox/таблицы заданий). Брокер **не** входит в синхронный путь API: при его недоступности upload всё равно отвечает 202, строка ждёт в `job_outbox`; `/health/ready` от брокера не зависит.
|
||
|
||
### Что сохранено в момент 202
|
||
|
||
1. Все байты оригинала в приватном S3 `staging/<random>` (PUT с Content-MD5, SHA-256 в метаданных объекта и в БД). Ключ генерирует сервер, filename в ключ не попадает.
|
||
2. Метаданные вложения (`state=queued`, size, sha256, размеры, будущий конечный ключ).
|
||
3. Намерение обработать: строка `attachment_jobs` (job_id, attempt=1, max_attempts) и строка `job_outbox` с JSON-сообщением **в той же транзакции**.
|
||
|
||
Сообщение в брокере на момент 202 может ещё не существовать — это нормально: его гарантирует outbox, а не HTTP-запрос. Остановка API сразу после 202 работу не теряет (тест A).
|
||
|
||
### Состояния и окна отказа
|
||
|
||
Внутреннее `pending` (приём идёт) наружу не видно; публичные: `queued → processing → ready | failed`.
|
||
|
||
| Окно отказа | Что произойдёт | Где доказано |
|
||
| --- | --- | --- |
|
||
| после staging PUT до COMMIT задания | строка pending + staging-объект; клиенту ошибка (не 202). Сборщик через grace удаляет и строку, и объект | lab4 `test_attachment_consistency.py` (crash_after_s3_put теперь между staging и COMMIT) |
|
||
| после COMMIT до publish | строка outbox осталась; sweeper любого процесса публикует через `RELAY_FAST_PATH_GRACE_SECONDS` | `test_a` (api-fault-publish, `FAULT_INJECTION=crash_after_commit`) |
|
||
| после publish до подтверждения в outbox | XADD выполнен, DELETE строки — нет -> повторная публикация, дубль в брокере -> worker no-op | `test_b` (api-fault-dup, `crash_after_publish`) |
|
||
| после записи S3 до COMMIT результата | сообщение в PEL; перезапущенный consumer читает свой PEL, перехватывает свою аренду, перезаписывает **те же** байты, COMMIT | `test_c` (`fault-crash-after-effects`) |
|
||
| после COMMIT результата до ack | повторная доставка -> claim видит succeeded -> `redelivery_noop already_succeeded`, ack | `test_d` (`fault-crash-before-ack`) |
|
||
| worker завис дольше аренды | сборщик аренд -> attempt+1 через outbox -> другой consumer -> ready; проснувшийся старый результат отсечён fencing'ом (`lease_lost`) | `test_h` (`fault-slow`) |
|
||
|
||
### Брокер: Redis Streams как durable at-least-once очередь
|
||
|
||
Выбран Redis Streams (разрешён README): тот же закреплённый образ, что и для кэша, но **отдельный сервис** с другими гарантиями. Кэш сессий — без persistence и с LRU-вытеснением; объединять их нельзя.
|
||
|
||
- **Durability:** `--appendonly yes --appendfsync always` — Redis отвечает на XADD только после fsync AOF. Успешный XADD — наш **publisher confirm**: сообщение переживает рестарт/падение брокера с volume `brokerdata` (проверено в сценарии `worker_outage`: lag=1 до и после рестарта брокера). `--maxmemory-policy noeviction`: поток никогда не вытесняется; при переполнении XADD упадёт, строка останется в outbox.
|
||
- **Доставка at-least-once:** consumer group; XREADGROUP кладёт сообщение в PEL до XACK. **Consumer ack** worker делает только после COMMIT результата (или перехода в retry/failed) — это другая граница, чем confirm при публикации.
|
||
- **Упавший consumer:** имя consumer = `<hostname>-<поток>`; после `restart` контейнера hostname тот же, и consumer первым делом читает свой PEL (`XREADGROUP ... 0`). Если контейнер пересоздан, сообщения забирает любой живой consumer через `XAUTOCLAIM` после `JOB_CLAIM_IDLE_SECONDS` (75 с > аренды 60 с).
|
||
- **Prefetch/конкуренция:** каждый consumer-поток берёт `COUNT 1`, потоков `WORKER_CONCURRENCY=2`, контейнеров `WORKER_REPLICAS=1` -> одновременно в обработке не больше 2 сообщений.
|
||
- **Очистка потока:** `XTRIM MINID` до минимума из (самый старый pending, last-delivered-id+1) — удаляются только доставленные и подтверждённые записи.
|
||
- **Содержимое сообщения** — ровно `contracts/jobs.schema.json` (`schema_version, job_id, type, attachment_id, pipeline_version, attempt, created_at`): без байтов, credentials, URL и filename. Worker проверяет схему строго; мусор подтверждается и логируется (`test_j`); сообщение, доставленное больше `JOB_MAX_DELIVERIES` раз, переводит задание в `failed poison_message`.
|
||
|
||
### Transactional outbox
|
||
|
||
`job_outbox` пишется в одной транзакции с `attachment_jobs` и `state=queued`. Публикация:
|
||
|
||
- **быстрый путь** — после отправки 202 (FastAPI background task) API берёт свою строку `FOR UPDATE SKIP LOCKED`, делает XADD, удаляет строку, пишет событие `published`, COMMIT;
|
||
- **sweeper** — в каждой реплике API и в worker раз в `RELAY_POLL_INTERVAL_SECONDS` публикует строки с `available_at <= now()`. У свежей строки `available_at = now()+2 c`, чтобы не соревноваться с быстрым путём; у retry — время следующей попытки (так реализован отложенный повтор без delayed-очереди брокера).
|
||
|
||
`SKIP LOCKED` разносит строки между relay; несколько relay безопасны. Сбой между XADD и COMMIT relay даёт дубль — это и есть at-least-once, дубль гасит идемпотентный worker.
|
||
|
||
### Worker, идемпотентность и аренды
|
||
|
||
- **Ключ идемпотентности эффекта** — `(attachment_id, pipeline_version, variant)`: PRIMARY KEY `attachment_variants` + **детерминированные ключи S3** `final/<id>/original`, `final/<id>/p1/{thumbnail.jpg,crop.jpg,optimized.webp}`. Повтор пишет те же байты по тем же ключам (Pillow-вывод детерминирован при одной версии библиотек — проверено в `test_a`/`test_c` сравнением SHA-256 с эталонной загрузкой). `job_id` не меняется при redelivery и retry.
|
||
- **Аренда (lease)**: claim атомарно ставит `status=processing, lease_token=<uuid>, lease_owner=<consumer>, lease_until=now()+JOB_TIMEOUT_SECONDS` (`SELECT ... FOR UPDATE`). Захват разрешён только для текущей попытки и если задание queued, или аренда истекла, или аренда принадлежит этому же consumer (его прошлая инкарнация мертва: consumer обрабатывает одно сообщение за раз).
|
||
- **Fencing**: публикация результата, retry и failed выполняются с условием `lease_token = <мой> AND status='processing'`. Worker, у которого аренду отобрали, ничего не может изменить (`test_h`, событие `lease_lost`). `ready` никогда не откатывается в processing старым дублем; `attachments.pipeline_version` обновляется только если новая версия ≥ текущей.
|
||
- **Зависший vs долгий worker:** аренда (60 с) > максимальной длительности попытки (обработка ≤ 30 с + S3-дедлайны), это проверяется при старте конфигурации. Пока аренда не истекла, второй worker задание не возьмёт (`leased_by_other`, ack дубля). Истекла + `JOB_LEASE_GRACE_SECONDS` -> сборщик аренд переводит задание в queued attempt+1 через outbox. Healthcheck worker'а — heartbeat, который пишется, только пока **все** consumer-потоки проходят цикл.
|
||
- **Staging** удаляется worker'ом после COMMIT и XACK; если не удалось — сборщик (проход D) удалит staging у ready-вложений. Staging failed-вложений хранится `STAGING_RETENTION_SECONDS` (24 ч) для replay, затем удаляется (replay после этого отклоняется: нужен повторный upload). Текущую работу (queued/processing) сборщик не трогает.
|
||
|
||
### Варианты изображений (pipeline_version = 1)
|
||
|
||
| Вариант | Формат | Правило | Параметры |
|
||
| --- | --- | --- | --- |
|
||
| thumbnail | JPEG | вписан в 256×256, пропорции, без увеличения, округление вниз (мин. 1 px): 320×200 → 256×160 | quality 85, optimize, baseline, 4:2:0 |
|
||
| crop | JPEG | центрированный квадрат min(w,h) → 128×128 (маленькие увеличиваются) | quality 85 |
|
||
| optimized | WebP | вписан в 1280×1280 без увеличения | lossy, quality 80, method 4; уменьшение каждого маленького файла не обещается |
|
||
|
||
Общее: EXIF orientation применяется **до** расчёта размеров (400×100 c orientation=6 → thumbnail 64×256); прозрачность компонуется на белый (масштабирование RGBA в Pillow — с premultiplied alpha); **EXIF и XMP не копируются** (Pillow пишет их только при явной передаче), ICC-профиль сохраняется, чтобы не исказить цвет. Целочисленная арифметика размеров исключает ошибки округления float.
|
||
|
||
**Ограничения ресурсов worker** (недоверенный файл, даже прошедший проверки API):
|
||
|
||
| Ресурс | Ограничение | Поведение |
|
||
| --- | --- | --- |
|
||
| байты | staging-объект > `MAX_UPLOAD_BYTES` не читается; SHA-256 и размер сверяются с БД | failed `invalid_image` / `processing_failed` |
|
||
| пиксели | размеры из заголовка до декодирования, > `MAX_IMAGE_PIXELS` | failed `invalid_image` |
|
||
| память | обработка в отдельном процессе (forkserver) с `RLIMIT_AS = WORKER_IMAGE_MEMORY_MB` (1024) | MemoryError/смерть процесса → failed `resource_limit` |
|
||
| время | процесс убивается через `WORKER_IMAGE_TIMEOUT_SECONDS` (30), `RLIMIT_CPU` — страховка | временная ошибка `processing_timeout`, повтор ≤ JOB_MAX_ATTEMPTS |
|
||
|
||
JPEG декодируется сразу в уменьшенном масштабе (`draft`), поэтому 40 Мп JPEG — пик 46 MiB; худший случай 40 Мп RGBA PNG — **361 MiB** (было 518 MiB, пока альфа компоновалась до масштабирования; порядок операций изменён). Отсюда лимит контейнера worker 1280 MiB при 2 подпроцессах. Замер: `evidence/local/imaging_memory.txt`; проверка самих лимитов: `python -m src.imaging FILE --memory-mb 200` → `resource_limit`, `--timeout 0.3` → `timeout`.
|
||
|
||
### Retry, backoff, DLQ, replay
|
||
|
||
- **Классификация ошибок.** Временные: S3 недоступен/таймаут, таймаут обработки, внедрённый `injected_transient` → retry. Постоянные: битое/неподдерживаемое изображение, превышение пикселей/байт, лимит памяти, нет источника, несовпадение SHA-256 staging → сразу `failed` без повторов (`test_f`). Если недоступна сама БД, сообщение **не** подтверждается и вернётся из PEL — решение о retry без БД принять нельзя.
|
||
- **Backoff с jitter** («equal jitter»): `d = min(JOB_RETRY_MAX_SECONDS, JOB_RETRY_BASE_SECONDS·2^(attempt−1))`, задержка равномерно в `[d/2, d]` (нижняя граница гарантирует паузу, случайная часть разносит повторы многих заданий). Реализован через `job_outbox.available_at`: попытка не начнётся раньше (проверено по журналу в `test_e`).
|
||
- **Предел:** `JOB_MAX_ATTEMPTS=5`; затем `failed retry_exhausted`, запись в `dead_letters` (реестр failed/DLQ), событие в `job_events`.
|
||
- **Replay** — только явная команда оператора (`ops.py jobs replay`). Разрешён только для `failed`; успешное задание **не исполняется повторно** (`noop`, событие `replay_refused`); без staging-источника — отказ. Новая попытка: attempt+1, свежий бюджет попыток, `replay_count+1`, `dead_letters.replayed_at`, публикация через outbox (`test_g`).
|
||
|
||
### Роли и сервисы
|
||
|
||
| Роль | Сервис | Версия | Health/readiness | Volume | Сеть/порт | Credentials |
|
||
| --- | --- | --- | --- | --- | --- | --- |
|
||
| load_balancer | `lb` | haproxy:2.8.30-alpine | `/lb-health`; проверка `/health/ready` реплик | — | backend; 127.0.0.1:8080 (единственный публичный), 8404 stats | — |
|
||
| api ×2 | `api` | сборка из Dockerfile | `/health/ready` (PG + схема 005 + не drain) | нет (read-only rootfs, tmpfs /tmp) | backend, storage, queue; 8080 только внутри | secrets: database_url, cache_url, s3_*, broker_url |
|
||
| worker | `worker` | тот же образ | heartbeat-файл < 90 с | нет (read-only, tmpfs) | backend, storage, queue | secrets: database_url, s3_*, broker_url |
|
||
| broker | `broker` | redis:7.4.1-alpine, AOF always, noeviction | `redis-cli ping` | brokerdata | queue (internal) | secrets: broker_password |
|
||
| postgres | `postgres` | postgres:16.4-alpine | pg_isready | pgdata | backend | secrets: postgres_password |
|
||
| кэш сессий | `redis` | redis:7.4.1-alpine, без persistence | ping | — | backend | secrets: redis_password |
|
||
| s3 | `s3` | chrislusf/seaweedfs:4.50 | /healthz + прогрев `ops.py wait-s3` | s3data | storage (internal) | secrets: s3_config.json |
|
||
| bootstrap | `migrate`, `s3-init` | тот же образ | one-shot, идемпотентны | — | backend / storage | — |
|
||
|
||
Топология брокера (поток + группа) создаётся кодом идемпотентно (`XGROUP CREATE ... MKSTREAM`, BUSYGROUP = no-op).
|
||
|
||
### Переменные `.env.example` → реальная конфигурация
|
||
|
||
| Логическое имя (skeleton) | Реализация |
|
||
| --- | --- |
|
||
| `BROKER_URL_FILE` | `/run/secrets/broker_url` (создаёт `init_secrets.py`) |
|
||
| `WORKER_CONCURRENCY=2` | число consumer-потоков в контейнере worker (prefetch 1 на поток) |
|
||
| `JOB_MAX_ATTEMPTS=5` | `attachment_jobs.max_attempts` при создании задания |
|
||
| `JOB_TIMEOUT_SECONDS=60` | срок аренды; ≥ `WORKER_IMAGE_TIMEOUT_SECONDS + 20` (проверка при старте) |
|
||
| `STAGING_RETENTION_SECONDS=86400` | хранение staging failed-вложений (окно replay) |
|
||
| дополнительно | `JOB_LEASE_GRACE_SECONDS`, `JOB_CLAIM_IDLE_SECONDS`, `JOB_MAX_DELIVERIES`, `JOB_RETRY_BASE/MAX_SECONDS`, `WORKER_IMAGE_TIMEOUT_SECONDS`, `WORKER_IMAGE_MEMORY_MB`, `RELAY_*`, `BROKER_STREAM/GROUP`, `PIPELINE_VERSION`, `WORKER_REPLICAS` — описаны в `.env.example` |
|
||
|
||
### Что изменено относительно lab4
|
||
|
||
- `migrations/005_async_processing.sql`: состояния `queued/processing/failed`, `staging_key`, `error_code`, `pipeline_version`; таблицы `attachment_variants`, `attachment_jobs`, `job_outbox`, `dead_letters`, `job_events`.
|
||
- `src/main.py`: upload → staging + задание + outbox → **202**; content: 409 для queued/processing/failed, варианты; сообщение с failed-вложением → 409, с queued/processing — разрешено.
|
||
- Новые модули: `src/broker.py`, `src/outbox.py`, `src/jobs.py` (переходы состояний), `src/worker.py`, `src/imaging.py`, `src/jobs_admin.py`.
|
||
- `src/reconcile.py`: префиксы `staging/`, `final/`, `originals/` (lab4), проход D — очистка staging.
|
||
- `compose.yaml`: сервисы `broker`, `worker`, `api-fault-publish`, `api-fault-dup`, сеть `queue`; `compose.faults.yaml`.
|
||
- Тесты lab4, ожидавшие 201, переведены на 202 + ожидание ready (`test_attachments.py`, `test_attachment_consistency.py`, `s3_outage.py`, `upload_memory.py`). Публичные `tests/` и контракт не изменялись.
|
||
|
||
## Доказательства критериев
|
||
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||
| --- | --- | --- | --- |
|
||
| Публичный smoke | `make test` | `PASS: lab5 public API scenario` (202 → ready, оригинал, JPEG thumbnail 256×160) | evidence/local/smoke.txt |
|
||
| Минимум lab4 сохранён | `student-tests/run_all.py` через 2 реплики | 91 тест OK (33 skip — требуют сеть compose), race 100/100, persistence и failover PASS | evidence/local/student-tests.txt, persistence.txt, failover.txt |
|
||
| 3: 202 только после durable staging + задания | `test_pipeline.py`, `test_i`, `test_a` | 202 приходит до публикации, задача доходит до ready даже при падении API сразу после 202 | pipeline_and_attachments.txt, pipeline_faults.txt |
|
||
| 3: отдельные broker и worker, durable, at-least-once, ack после эффекта | compose: `broker` (AOF always) + `worker`; `test_c`, `test_d` | ack только после COMMIT; падение до ack → повторная доставка без дубля | compose.yaml, pipeline_faults_events.txt |
|
||
| 3: worker недоступен → API не делает resize | `make test-worker-outage` | worker остановлен: 202, GET queued, content 409, сообщения 201; после старта worker — ready | worker_outage.txt/.json |
|
||
| 3: состояния queued/processing/ready/failed, original неизменен, thumbnail по контракту | `test_pipeline.py` | SHA-256 оригинала совпадает; thumbnail 256×160 по SOF-заголовку JPEG | pipeline_and_attachments.txt |
|
||
| 3: ограниченный retry, failed с безопасным error_code, повтор не создаёт 2-й набор | `test_e`, `test_g`, `assert_single_result` | ровно 3 строки variants и 1 событие succeeded во всех сценариях; `retry_exhausted`/`invalid_image` | pipeline_faults.txt |
|
||
| 3: демонстрация worker stop → upload → рестарт API → рестарт broker → worker → ready | `make test-worker-outage` | lag=1 до и после рестарта брокера, ready через ~0.03 с после старта worker | worker_outage.txt |
|
||
| 4: crop 128 и WebP; лимиты bytes/pixels/time/memory | `test_pipeline.py`, `python -m src.imaging` | crop 128×128, WebP по RIFF-заголовку; EXIF удалён; orientation/alpha/малые исходники; `resource_limit`, `timeout` | pipeline_and_attachments.txt, imaging_memory.txt |
|
||
| 4: outbox, crash между COMMIT и publish | `test_a` (api-fault-publish) | `fault_injected` от api-fault-publish, `published` другим процессом, attempt=1, ready | pipeline_faults_events.txt |
|
||
| 4: backoff+jitter, постоянные/временные, DLQ, безопасный replay | `test_e`, `test_f`, `test_g` | интервалы в [d/2, d]; permanent без повторов; replay → ready; повторный replay → noop | pipeline_faults.txt |
|
||
| 4: остановка worker после записи объекта до ack | `test_c`, `test_d` | `lease_takeover` своим consumer после рестарта; те же SHA-256; `redelivery_noop already_succeeded` | worker_fault_log.txt |
|
||
| 4: lease для зависшего processing, ограниченная конкуренция, очистка staging | `test_h`, `test_i` | `lease_expired` → attempt 2 у другого consumer → ready; старый `lease_lost`; staging_key=NULL | pipeline_faults_events.txt |
|
||
|
||
## Эксперименты и отказы
|
||
|
||
Локальная песочница: 2 vCPU, 7 GiB RAM, Linux, Python 3.13 (в образе — 3.12.7), без лимитов cgroup. Набор: синтетические изображения (`tests/fixtures/sample.png` 320×200, генерируемые 40 Мп PNG/JPEG). Повторов: сценарии отказов — 1 полный прогон, все 10 PASS; задержка — 30 последовательных загрузок. Основной compose-стенд: Windows 10, 32GB, Ryzen 5 7500f; доказательства в `/evidence`.
|
||
|
||
| Измерение | Результат |
|
||
| --- | --- |
|
||
| upload → 202 (sample.png, 109 KiB) | p50 16 мс, p95 29 мс |
|
||
| upload → ready (опрос каждые 0.2 с) | p50 0.44 с, p95 0.45 с, max 0.45 с |
|
||
| пик RSS подпроцесса обработки | 23 MiB (320×200), 46 MiB (40 Мп JPEG), 361 MiB (40 Мп RGBA PNG) |
|
||
| время обработки 40 Мп | JPEG 0.2 с, RGBA PNG 1.8 с |
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Восстановление / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| worker остановлен, upload | 202 queued, content 409, остальной API работает | так и есть, сообщения 201 | ready после старта worker; потерь нет |
|
||
| рестарт API и broker (volumes целы) при неподтверждённой задаче | задача остаётся в потоке | lag=1 до и после | — / нет |
|
||
| API умер после COMMIT до XADD | sweeper другого процесса публикует | published другим actor через ~2 с | ≤ RELAY_FAST_PATH_GRACE + 1 с / нет |
|
||
| API умер после XADD до подтверждения outbox | дубль, no-op | `redelivery_noop already_succeeded` | — / нет, 1 набор вариантов |
|
||
| worker умер после записи S3 до COMMIT | свой PEL после рестарта, те же байты | `lease_takeover`, SHA-256 = эталон | ~1–2 с (рестарт процесса) / нет |
|
||
| worker умер после COMMIT до XACK | повторная доставка no-op | `redelivery_noop already_succeeded` | ~1–2 с / нет |
|
||
| worker «завис» дольше аренды | новая попытка, fencing старой | `lease_expired` → ready на attempt 2 → `lease_lost` | аренда + grace + ≤5 с / нет |
|
||
| временные ошибки ×2 | backoff+jitter, ready на 3-й | задержки 0.5–1 с и 1–2 с (base 1, cap 4 в стенде отказов) | — |
|
||
| временная ошибка всегда | failed retry_exhausted, DLQ, replay | 5 попыток → failed → replay → ready → replay ещё раз = noop | — |
|
||
| мусор в потоке | ack, worker жив | pending=0 | — |
|
||
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
- **Один Docker-host:** брокер, PostgreSQL и S3 — по одному экземпляру. Выдерживаются рестарты и падения процессов с сохранением volumes, но не потеря диска/хоста. Redis без репликации: при потере volume брокера неопубликованные строки outbox сохранятся, а уже опубликованные, но не обработанные задачи потребуют повторной публикации (`jobs replay` работает только для failed; для queued без сообщения нужен ручной requeue — сборщик аренд покрывает только processing).
|
||
- **At-least-once + идемпотентность ≠ exactly-once:** дубли сообщений и повторная запись тех же объектов S3 возможны и ожидаемы; уникален только опубликованный результат. Детерминизм байтов вариантов гарантирован в пределах одной версии Pillow/libjpeg/libwebp; при обновлении библиотек нужна новая `pipeline_version` (версионирование нескольких pipeline — трек 5, не заявлен).
|
||
- Fencing защищает БД, но не S3: «проснувшийся» старый worker может перезаписать объект варианта теми же (детерминированными) байтами после публикации результата.
|
||
- Классификация ошибок упрощена: таймаут обработки считается временным, поэтому «тяжёлый» файл может занять до 5 попыток по 30 с.
|
||
- Маркеры отказов в filename работают **только** при `WORKER_FAULTS=true` (`compose.faults.yaml`); в обычном стенде filename на обработку не влияет.
|
||
- Старые ready-вложения lab4 остаются без вариантов (запрос варианта → 404 по контракту); фоновой догенерации нет.
|
||
- HTTP без TLS — только локальный учебный стенд (TLS — lab7).
|
||
|
||
## Вопросы защиты — кратко
|
||
|
||
- **Publisher confirm vs consumer ack.** Confirm — брокер принял и сохранил сообщение (у нас: ответ XADD после fsync AOF), это граница «producer → брокер»; после него relay удаляет строку outbox. Ack (XACK) — consumer сообщает, что обработка устойчиво завершена (COMMIT результата/перевода в retry/failed), это граница «брокер → consumer»; до него сообщение остаётся в PEL и будет доставлено снова.
|
||
- **Что сохранено в момент 202?** Байты в S3 staging, метаданные, задание и outbox в одной транзакции PostgreSQL. Сообщения в брокере может ещё не быть — его гарантирует outbox.
|
||
- **Почему повторная доставка нормальна и где ключ идемпотентности?** At-least-once неизбежно даёт дубли (падение до ack, повтор publish). Ключ эффекта — `(attachment_id, pipeline_version, variant)`: PK `attachment_variants` + детерминированные ключи S3; задание — `job_id` (UNIQUE `(attachment_id, pipeline_version)`); повтор успешного — no-op с ack.
|
||
- **Как отличить зависший worker от долго работающего?** Аренда с заведомо большим сроком, чем максимальная попытка (жёсткий таймаут подпроцесса + дедлайны S3). Пока аренда действует — задание не отдаётся второму worker; после истечения + grace — новая попытка, а результат старой отсекается fencing-токеном. Heartbeat контейнера проверяет, что все consumer-потоки живы.
|