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>
13 KiB
13 KiB
Отчёт — лабораторная 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.
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):
- Блок
try/exceptвprocess_jobизначально не покрывал загрузку сгенерированных вариантов в S3 — ошибка на этом шаге "сбегала" из структурированного retry-механизма. Исправлено расширением границtry. - 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 не реализован.