forked from mtusi2026/mtusi2026lab5
Переиспользован стек lab4 (LB/2 реплики/Postgres/SeaweedFS). upload теперь 202 queued; отдельный worker-процесс генерирует thumbnail/crop/optimized. Transactional outbox закрывает разрыв COMMIT/publish; durable retry (job_retry_schedule) переживает падение worker во время backoff; lease recovery через XAUTOCLAIM; DLQ-реестр (job_failures) с явным operator replay (scripts/replay_failed.py). make test/test-persistence/test-failover/ validate зелёные; в процессе экспериментов найдены и исправлены два реальных бага (неполный try/except вокруг S3-записи вариантов, ошибка типов asyncpg в построении interval) — см. REPORT.md и evidence/. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
98 lines
13 KiB
Markdown
98 lines
13 KiB
Markdown
# Отчёт — лабораторная 5
|
||
|
||
- Автор, группа: Сарибекян, БПИ2303
|
||
- Целевая оценка: 4
|
||
- Commit/PR: см. ветку `solution/БПИ2303-Сарибекян`
|
||
- Использованные источники, библиотеки и помощь ИИ: база lab4 (FastAPI/asyncpg/redis-py/Pillow/boto3/SeaweedFS/Nginx) плюс Redis Streams как брокер (тот же Redis, что и под сессиями). Реализация подготовлена с помощью AI-ассистента (Claude Code); проверено `make check/test/test-persistence/test-failover/validate` и серией ручных экспериментов отказов (см. `evidence/`).
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Версии: Python 3.12.7, PostgreSQL 16.4, Redis 7.4.1, Nginx 1.27.2, SeaweedFS 3.73.
|
||
|
||
```sh
|
||
git clone <ваш форк>
|
||
cd mtusi2026lab5
|
||
mkdir -p secrets
|
||
openssl rand -hex 20 > secrets/postgres_password.txt
|
||
printf 'postgresql://messenger:%s@postgres:5432/messenger' "$(cat secrets/postgres_password.txt)" > secrets/database_url.txt
|
||
printf 'redis://redis:6379/0' > secrets/cache_url.txt
|
||
printf 'messenger-api' > secrets/s3_access_key_id.txt
|
||
openssl rand -hex 20 > secrets/s3_secret_access_key.txt
|
||
AK=$(cat secrets/s3_access_key_id.txt); SK=$(cat secrets/s3_secret_access_key.txt)
|
||
sed -e "s/__S3_ACCESS_KEY_ID__/$AK/" -e "s/__S3_SECRET_ACCESS_KEY__/$SK/" \
|
||
infra/seaweedfs/s3.json.template > secrets/s3.json
|
||
chmod 600 secrets/*.txt secrets/s3.json
|
||
printf 'SESSION_TTL_SECONDS=3600\nMAX_UPLOAD_BYTES=10485760\nMAX_IMAGE_PIXELS=40000000\nJOB_MAX_ATTEMPTS=5\nJOB_TIMEOUT_SECONDS=60\n' > .env
|
||
|
||
docker compose --env-file .env config --quiet
|
||
docker compose --env-file .env up -d --build
|
||
curl -s localhost:8080/health/ready
|
||
|
||
make test
|
||
chmod +x scripts/restart.sh scripts/stop-one.sh
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
|
||
# после отказа одной реплики: docker compose start api1 (или api2), повторить для второй.
|
||
```
|
||
|
||
Остановка: `docker compose stop`. Намеренное удаление: `docker compose down -v`.
|
||
|
||
## Архитектура и решения
|
||
|
||
```
|
||
Клиент → lb → api1/api2 → durable staging (= финальный S3-prefix) + attachments(status=queued) + job_outbox (1 транзакция Postgres)
|
||
│
|
||
▼ best-effort publish + фоновый relay (устраняет разрыв COMMIT↔publish)
|
||
Redis Streams (consumer group "workers")
|
||
│
|
||
▼
|
||
worker: thumbnail/crop/optimized → S3 + attachment_variants → status=ready
|
||
```
|
||
|
||
- **Брокер — Redis Streams на том же Redis**, что уже используется под сессии (AOF-персистентность уже настроена в lab2). Выбор задокументирован: это разрешённая контрактом альтернатива RabbitMQ/NATS JetStream, и переиспользование инфраструктуры избавляет от отдельного сервиса.
|
||
- **Staging = финальный S3-prefix**: контракт явно разрешает эту честную границу, если staging уже в S3 (см. `contracts/attachment-states.md`). Оригинал не "переезжает" между каталогами — он валидируется и сохраняется синхронно при upload (как в lab4), меняется только то, что готовность (`ready`) теперь выставляет **worker**, не API.
|
||
- **Transactional outbox** (`app/outbox.py`): `job_outbox` пишется в той же транзакции, что `INSERT` в `attachments`. После COMMIT — best-effort немедленная публикация; фоновый `relay_loop` (в каждой API-реплике, тик каждые 2с) публикует всё, что осталось неопубликованным дольше 1с. Проверено: искусственно созданная неопубликованная строка была подхвачена и доведена до `ready` без участия API-запроса (`evidence/outbox_gap.txt`).
|
||
- **Durable delayed retry**: Redis Streams не умеет отложенную доставку, поэтому backoff реализован через `job_retry_schedule` (Postgres) + `retry_scheduler_loop` в worker, а не через `sleep()` в процессе — переживает падение worker в любой момент backoff-окна.
|
||
- **Lease recovery**: `XAUTOCLAIM` (`broker.reclaim_stale`, `JOB_TIMEOUT_SECONDS`=60с) забирает незаподтверждённые сообщения у возможно умершего воркера.
|
||
- **Идемпотентность эффекта**: `process_job` — no-op для уже `ready`/`failed`; `attachment_variants` — `ON CONFLICT DO UPDATE`; финальный статус — условный `UPDATE ... WHERE status != 'ready'`.
|
||
- **DLQ упрощённо**: таблица `job_failures` (не отдельная очередь брокера) — читается оператором напрямую; explicit replay — `scripts/replay_failed.py`.
|
||
- **Совместимость с lab4**: `attachment_ids` в сообщении теперь может ссылаться на `queued/processing` вложения (не только `ready`), запрещён только `failed` (`409`) — согласно обновлённому контракту lab5.
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||
| --- | --- | --- | --- |
|
||
| upload 201→202 | `make test` | `PASS: lab5 public API scenario...` (включает ожидание ready, проверку thumbnail 256×160) | вывод команды |
|
||
| Персистентность | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `PASS` | вывод команды |
|
||
| Failover (дважды) | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | `successful_writes:101/103, failed_attempts:0` | вывод команды |
|
||
| Worker стоп→upload→API restart→worker старт→ready | ручной сценарий | `queued`→`409` на content→после старта worker: `ready` с 3 вариантами | `evidence/worker_resilience.txt` |
|
||
| Ограниченный retry с backoff+jitter | симулированный transient failure (`_handle_failure`, attempt=1) | `job_retry_schedule` с `next_attempt_at`+1.9с; автопланировщик republish; `attempt=2` → `ready` | `evidence/retry_backoff.txt` |
|
||
| DLQ/failed + явный replay | симулировано attempt=5 → `failed` | `job_failures` запись, `409` на content, `scripts/replay_failed.py` → `queued`→`ready` | `evidence/dlq_and_replay.txt` |
|
||
| Разрыв COMMIT/publish (outbox) | вставлена неопубликованная `job_outbox`-строка | фоновый relay опубликовал её сам, вложение дошло до `ready` | `evidence/outbox_gap.txt` |
|
||
| Повторная доставка ready-задачи — no-op | ручной повторный `process_job` на готовом вложении | лог `"already ready; no-op"`, данные не изменены | `evidence/outbox_gap.txt` |
|
||
| crop 128×128, optimized WebP (4) | тот же smoke/ручной upload | 3 варианта с верными размерами в ответе | `evidence/worker_resilience.txt`, `evidence/retry_backoff.txt` |
|
||
| `make validate` | `make validate PYTHON=.venv/bin/python` | `PASS` | вывод команды |
|
||
|
||
## Эксперименты и отказы
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Восстановление / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| `docker compose stop worker`, upload, `docker compose restart api1 api2` (worker всё ещё выключен) | Вложение остаётся `queued`, API-рестарт не теряет job | подтверждено, `status: queued` после рестарта API | нет потерь; задача ждёт worker |
|
||
| `GET .../content` при `status=queued` | `409`, не `200`/`404` | `409 conflict: attachment is not ready yet` | — |
|
||
| Старт worker после простоя | Принятая ранее задача доходит до `ready` | `ready` с 3 вариантами через ~5с после старта | без повторной загрузки файла |
|
||
| Симулированный transient failure, attempt=1 | Durable retry schedule, не "тихая" потеря | `job_retry_schedule` создана, автопубликация через ~2с, `attempt=2` → `ready` | без потерь, с управляемой задержкой |
|
||
| Симулированное исчерпание попыток (attempt=5) | `failed` + DLQ-запись, `409` на content | подтверждено; `scripts/replay_failed.py` восстановил до `ready` | без потерь, восстановление — операторское решение |
|
||
| Неопубликованная `job_outbox`-строка (разрыв COMMIT/publish) | Фоновый relay публикует без вмешательства | задача дошла до `ready` автоматически | без потерь, без ручного создания нового задания |
|
||
| Повторный вызов `process_job` на `ready`-вложении | No-op, без дублей/изменений | лог `already ready; no-op` | — |
|
||
|
||
**Ограничение:** трек исследования уровня 5 (очередь под нагрузкой / доказанная идемпотентность с fault injection) не выполнялся — цель лабы — оценка 4. Нагрузочный тест `tests/load.py` на нескольких одновременных upload с измерением throughput конвейера не проводился отдельно от общего `make test`.
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
- Найдено и исправлено **две реальные ошибки** в процессе ручных экспериментов (не поймались бы одним happy-path smoke):
|
||
1. Блок `try/except` в `process_job` изначально не покрывал загрузку сгенерированных вариантов в S3 — ошибка на этом шаге "сбегала" из структурированного retry-механизма. Исправлено расширением границ `try`.
|
||
2. SQL-ошибка типов `asyncpg` (`($1 || ' seconds')::interval` с параметром-`float`) в `app/worker.py` и `app/outbox.py` — заменено на `($1 * interval '1 second')`.
|
||
- `WORKER_CONCURRENCY` из `.env.example` не используется впрямую как числовой множитель параллельных задач — в текущей реализации один worker-процесс обрабатывает задания последовательно (`consume_loop` с `count=1`), конкурентность между задачами не реализована отдельно от конкурентности между контейнерами worker (которых здесь один). Для реальной параллельности нужно либо несколько worker-реплик, либо `asyncio.gather` нескольких consume-корутин в одном процессе — не сделано ввиду бюджета времени этой лабы.
|
||
- Очистка staging (`STAGING_RETENTION_SECONDS`) не реализована отдельным cron/job — поскольку staging совпадает с финальным хранилищем, "неудачные/непривязанные" объекты — это ровно та же категория orphan-объектов, что в lab4, и покрывается тем же `scripts/reconcile_attachments.py` (перенесён без изменений; здесь не переиспользован явно, но логика применима).
|
||
- Трек исследования уровня 5 не реализован.
|