forked from mtusi2026/mtusi2026lab5
118 lines
13 KiB
Markdown
118 lines
13 KiB
Markdown
# Отчёт — лабораторная 5
|
||
|
||
- Автор, группа: Самсонов Александр, БВТ2303
|
||
- Целевая оценка: 4
|
||
- Commit/PR: локально, до публикации
|
||
- Источники и помощь ИИ: контракт лабораторной, [RabbitMQ reliability](https://www.rabbitmq.com/docs/reliability), перенос стенда lab4. Реализацию и прогон проверок помог сделать ИИ в Cursor.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Нужны Docker Engine с Compose v2 и Python 3.9+ для публичных тестов. Образ API и worker — Python 3.12.6. Проверка выполнена в WSL Ubuntu 22.04: Docker 29.1.3, Compose 2.40.3.
|
||
|
||
```sh
|
||
cp .env.example .env
|
||
chmod +x scripts/up.sh scripts/restart.sh scripts/stop-one.sh scripts/restore-api.sh scripts/stop-worker.sh scripts/start-worker.sh
|
||
docker compose --env-file .env -f compose.yaml up -d --build --scale api=2 --remove-orphans
|
||
```
|
||
|
||
Тот же запуск: `sh scripts/up.sh`. Дождитесь `GET http://127.0.0.1:8080/health/ready` → `{"status":"ok"}`.
|
||
|
||
Публичный порт только у `lb`: `127.0.0.1:8080`. У API, worker, PostgreSQL, Valkey, RustFS и RabbitMQ порты наружу не опубликованы. Миграции выполняет одноразовый `migrate`, приватный bucket создаёт одноразовый `s3-init`.
|
||
|
||
Остановка без удаления данных:
|
||
|
||
```sh
|
||
docker compose --env-file .env -f compose.yaml stop
|
||
```
|
||
|
||
Удаление учебных volumes:
|
||
|
||
```sh
|
||
docker compose --env-file .env -f compose.yaml down -v
|
||
```
|
||
|
||
После `scripts/stop-one.sh` остановленная реплика не поднимается сама. Вернуть её: `sh scripts/restore-api.sh`. Остановить и снова запустить только worker: `scripts/stop-worker.sh` и `scripts/start-worker.sh`.
|
||
|
||
Образы: `python:3.12.6-slim-bookworm`, `postgres:16.6-bookworm`, `valkey/valkey:8.0.2`, `traefik:v3.7.16`, `rustfs/rustfs:1.0.4`, `rabbitmq:3.13.7-alpine`.
|
||
|
||
Healthcheck RabbitMQ вызывает `rabbitmq-diagnostics --timeout 5 -q ping`, а timeout самой проверки Docker — 10 с. Короткий timeout здесь нельзя ставить: Docker обрывает diagnostics, и этот обрыв останавливает брокер.
|
||
|
||
## Архитектура
|
||
|
||
```
|
||
Клиент → Traefik → API ×2 → PostgreSQL (пользователи, чаты, сообщения, метаданные, jobs, outbox)
|
||
→ Valkey (сессии, AOF)
|
||
→ RustFS (staging, оригинал, варианты)
|
||
→ RabbitMQ quorum (wake-up, не байты)
|
||
→ worker (отдельный процесс: lease, resize, ack)
|
||
```
|
||
|
||
Из lab4 сохранены две реплики, общий PostgreSQL и Valkey, Traefik без sticky, `X-Instance-Id`, идемпотентность POST сообщения, drain по SIGTERM, приватный bucket и проверка PNG/JPEG по заголовку до распаковки. Upload больше не делает resize и не кладёт оригинал в конечный ключ.
|
||
|
||
`/health/ready` отвечает 200, только если живы PostgreSQL, Valkey и bucket. Недоступность worker или RabbitMQ не переводит API в синхронный resize и не обязана ронять ready: намерение уже лежит в outbox. Период проверки Traefik — 1 с, timeout — 1 с.
|
||
|
||
Что устойчиво в момент 202:
|
||
|
||
1. Полные байты оригинала в приватном ключе `staging/<attachment_id>`.
|
||
2. Строка `attachments` со статусом `queued`, checksum и размерами.
|
||
3. Строка `attachment_jobs` и строка `outbox` в той же транзакции PostgreSQL.
|
||
|
||
Ответ 202 — снимок этого коммита (`status=queued`), даже если worker успеет закончить работу сразу после него. В сообщение брокера входят только поля `contracts/jobs.schema.json`: `job_id`, `attachment_id`, `pipeline_version=1`, `attempt`, `created_at`. Байтов, имени файла, ключа S3 и credentials там нет. Worker читает ключ staging из PostgreSQL.
|
||
|
||
Publisher confirm означает, что брокер принял durable-сообщение. Consumer ack ставится только после устойчивого эффекта: `ready` или финальный `failed` уже закоммичены, повторная доставка готовой job — no-op. Это не exactly-once доставка.
|
||
|
||
Разрыв между COMMIT и publish закрыт outbox. Релей крутится и в API, и в worker. Строка помечается опубликованной только после confirm. Если API умер после COMMIT, worker при старте публикует неопубликованные строки. Повторная публикация не создаёт второй job: ключ эффекта — `(attachment_id, pipeline_version)`.
|
||
|
||
Ключ идемпотентности варианта — `(attachment_id, pipeline_version, name)`. Повтор пишет те же ключи `originals/<id>` и `variants/<id>/{thumbnail,crop,optimized}`.
|
||
|
||
### Варианты
|
||
|
||
| Вариант | Формат | Правило | Параметры |
|
||
| --- | --- | --- | --- |
|
||
| thumbnail | JPEG | вписать в 256×256, без увеличения, пол вниз, минимум 1 px | quality 85, optimize, EXIF orientation до масштаба, альфа на белый, EXIF/ICC не пишутся |
|
||
| crop | JPEG | центральный квадрат, затем ровно 128×128, увеличение маленького исходника разрешено | те же параметры JPEG |
|
||
| optimized | WebP | вписать в 1280×1280 без увеличения | quality 80, method 6, EXIF/ICC/XMP не пишутся; меньший размер каждого маленького файла не обещается |
|
||
|
||
Фикстура 320×200 даёт thumbnail 256×160, crop 128×128 и optimized 320×200. `ready` ставится одной транзакцией только когда записаны оригинал и все три варианта.
|
||
|
||
### Ограничения обработки
|
||
|
||
- Байты: 10 MiB, отказ 413 до чтения лишнего тела.
|
||
- Пиксели: 40 000 000 по заголовку в API и повторно в worker до `load()`. Pillow `MAX_IMAGE_PIXELS` тот же. Decompression bomb — постоянная ошибка `payload_too_large`.
|
||
- Время: lease `JOB_TIMEOUT_SECONDS` (60). Истёкший `processing` sweeper возвращает в очередь и тратит попытку.
|
||
- Память worker: лимит контейнера 512 MiB. В логе старта это `memory_limit=536870912`.
|
||
- Конкуренция: `WORKER_CONCURRENCY=2`, у каждого канала `prefetch_count=1`. Worker не вычитывает очередь целиком.
|
||
|
||
### Повторы, DLQ, replay, staging
|
||
|
||
Постоянные ошибки (`invalid_image`, `payload_too_large`) сразу дают `failed` и копию сообщения в quorum-очередь `attachment.failed`. Реестр — таблица `job_failures`.
|
||
|
||
Временные ошибки (S3, обрыв, таймаут) делают backoff `min(30, 1 * 2^(attempt-1))` секунд плюс jitter до 20% и публикуют тот же `job_id` с новым `attempt`. После `JOB_MAX_ATTEMPTS=5` статус `failed`, код `retry_exhausted`.
|
||
|
||
`POST /api/v1/attachments/{id}/replay` доступен участнику чата. Если статус уже `ready`, ответ 200 и новая работа не создаётся (запись `job_replays.outcome=ignored_ready`). Если `failed`, тот же job снова становится `queued`. Пока job в `queued` или `processing`, replay отвечает 409.
|
||
|
||
Staging удаляется после коммита `ready`. Отдельный проход стирает оставшийся staging готовых объектов и staging `failed` старше `STAGING_RETENTION_SECONDS` (86400). Текущую очередь этот проход не трогает.
|
||
|
||
В `APP_ENV=lab` имена `__lab_fault_transient*` и `__lab_fault_permanent*` — учебные инъекции временной и постоянной ошибки. `CRASH_AFTER_S3=1` останавливает процесс после записи объектов и до ack.
|
||
|
||
## Доказательства
|
||
|
||
| Критерий | Команда | Результат | Файл |
|
||
| --- | --- | --- | --- |
|
||
| Публичный smoke: 202, ready, JPEG thumbnail 256×160, оригинал | `python3 tests/smoke.py --base-url http://127.0.0.1:8080` | PASS | evidence/smoke.txt |
|
||
| Restart API, worker, PostgreSQL, Valkey, RustFS и RabbitMQ, тот же токен и тот же файл | `python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080` | PASS. Скрипт перезапускает `api worker postgres valkey s3 rabbitmq`, volumes не удаляет | evidence/persistence.txt, evidence/restart-times.txt |
|
||
| Остановка обслужившей реплики | `python3 tests/resilience.py --mode failover --action-script scripts/stop-one.sh --base-url http://127.0.0.1:8080` | 2 реплики, 140 успешных записей, 4 ошибки, первое восстановление 3.658 с, PASS | evidence/failover.txt |
|
||
| Worker остановлен, upload 202, content 409, чат жив, рестарт RabbitMQ с volume сохраняет 2 сообщения, затем ready | `python3 scripts/grade4_demo.py` | `broker restart kept 2 then 2 process messages`, id `59f221a0-7fe3-47ba-9b87-97ac966357b7` | evidence/grade4.txt |
|
||
| Crop 128×128 и WebP 320×200, replay ready не плодит варианты | тот же прогон | id `113efcbd-9dcf-46bd-9af8-17d1c927f517`, `replay=ignored_ready`, вариантов 3 | evidence/grade4.txt |
|
||
| Crash между COMMIT и publish: брокер и API остановлены после 202, worker поднимает outbox без нового upload | тот же прогон | ready в PostgreSQL до старта API, id `50db09ac-d826-47a3-899a-ada58734390a` | evidence/grade4.txt |
|
||
| Постоянная ошибка, DLQ, явный replay не создаёт успешный дубль | тот же прогон | `invalid_image`, очередь `attachment.failed` есть, id `8e345bcd-8900-4287-9a06-4bb504ee6ae2` | evidence/grade4.txt |
|
||
| Backoff и две временные ошибки, затем один набор вариантов | тот же прогон | `retries=2 final_attempt=3`, id `c266f9bb-1d43-453e-b4b3-f1f0ef29a112` | evidence/grade4.txt |
|
||
| Остановка после записи S3 и до ack; повтор доводит тот же результат | тот же прогон | статус после падения `processing`, затем ready, вариантов 3, staging очищен, id `e2c19231-f4ec-4d67-a89b-f94c5325d91f` | evidence/grade4.txt |
|
||
| Истёкший lease зависшего processing | тот же прогон | `lease_expired`, затем ready, id `17531de7-4616-45fb-ac94-9d45355f846d` | evidence/grade4.txt |
|
||
|
||
Контейнеры, которые реально перезапускает `scripts/restart.sh`: `api`, `worker`, `postgres`, `valkey`, `s3`, `rabbitmq`. `lb` скрипт не трогает. После прогона failover остановленная реплика была возвращена `scripts/restore-api.sh`, чтобы стенд не остался с одной копией.
|
||
|
||
## Ограничения
|
||
|
||
Уровень 5 не делался: нет сравнения prefetch под нагрузкой и нет versioned pipeline. Один worker, внутри него два потребителя. Пока worker лежит дольше lease, сверка может положить в очередь ещё одно wake-up сообщение; эффект от этого не дублируется. Учебные имена `__lab_fault_*` работают только при `APP_ENV=lab`. Один и тот же ключ из `.env` является корневым ключом RustFS и ключом API. Это локальный стенд.
|