Files
mtusi2026lab5/REPORT.md
T
Artu-RitoandClaude Sonnet 5 bdba93f022 Лаба 5: Redis Streams очередь + асинхронная обработка изображений (оценка 4)
Переиспользован стек 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>
2026-10-30 01:21:42 +03:00

98 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 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 не реализован.