# Отчёт — лабораторная 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 не реализован.