Files
mtusi2026lab5-fork/REPORT.md
T
2026-11-16 20:30:12 +03:00

18 KiB
Raw Blame History

Отчёт — лабораторная 5

  • Автор, группа: Морозова Ольга Андреевна, БВТ2303
  • Целевая оценка: 4 (треки на 5 не заявлены)
  • Commit/PR: TODO после публикации
  • Использованные источники: README.md, COURSE.md, contracts/openapi.json, документация Go, MinIO (mc), PostgreSQL, Redis Streams, Nginx, Docker.
  • Библиотеки: Go 1.26 (stdlib), github.com/google/uuid v1.6.0, github.com/jackc/pgx/v5 v5.5.5, github.com/redis/go-redis/v9 v9.5.1, golang.org/x/crypto v0.23.0, github.com/minio/minio-go/v7 v7.0.72, golang.org/x/image v0.48.0. Тесты — Python 3 (stdlib).
  • Помощь ИИ: Deepseek — написание и проверка кода.

Запуск из чистого clone

Команды выполнялись в WSL2 (Ubuntu) на Windows 11. Требования: Docker 24+ (Compose v2), Python 3.9+ (для тестов), make.

Версии (фиксированные теги образов):

  • golang:1.26-alpine — build stage
  • alpine:3.20 — runtime stage
  • postgres:16.3-alpine — база данных
  • redis:7.2.5-alpine — кэш сессий и брокер (Redis Streams)
  • nginx:1.27.0-alpine — балансировщик
  • pgsty/silo:RELEASE.2026-10-26T00-00-00Z — S3-совместимое хранилище (MinIO-compatible)

Подготовка

git clone https://gitea.privcloud.tech/MiniLynx/mtusi2026lab5-fork
cd mtusi2026lab5-fork

# 1. Секреты (не входят в Git)
mkdir -p secrets
printf 'local-dev-postgres-password\n' > secrets/postgres_password.txt
printf 'postgres://messenger:local-dev-postgres-password@postgres:5432/messenger?sslmode=disable\n' > secrets/database_url.txt
printf 'redis://redis:6379/0\n' > secrets/cache_url.txt
printf 'minioadmin\n' > secrets/minio_root_user.txt
printf 'minioadmin-dev-password\n' > secrets/minio_root_password.txt
printf 'messenger-api\n' > secrets/s3_access_key_id.txt
printf 'messenger-api-dev-secret\n' > secrets/s3_secret_access_key.txt
chmod 600 secrets/*.txt

# 2. Локальный .env
cp .env.example .env
# ВАЖНО: В .env нужно исправить S3_ENDPOINT на s3:9000 (без http://)
sed -i 's|S3_ENDPOINT=.*|S3_ENDPOINT=s3:9000|' .env

# 3. Python для проверок
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-dev.txt

# 4. Скрипты
chmod +x scripts/migrate.sh scripts/restart.sh scripts/stop-one.sh scripts/restore-api.sh

Сборка и запуск

docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# Дождаться /health/ready
docker compose ps

Для запуска с другим количеством реплик добавить API_REPLICAS=$n перед docker compose --env-file .env up -d --build, где $n - желаемое количество реплик.

Тесты

make check
make validate PYTHON=.venv/bin/python
make test

# Persistence
make test-persistence ACTION_SCRIPT=scripts/restart.sh

# Failover
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
./scripts/restore-api.sh

# Собственные тесты (pipeline, сбои, лимиты)
make my_tests

Остановка (с сохранением volumes)

docker compose --env-file .env down --remove-orphans

Намеренное удаление учебных данных

docker compose --env-file .env down --remove-orphans -v
rm -f secrets/*.txt

Архитектура и решения

HTTP-клиент → Nginx (8080) → API (Go, x2, stateless)
                               │
                               ├──[S3 PUT]→ staging/  (S3, приватный bucket)
                               ├──[INSERT]→ Postgres: attachments (queued) + attachment_jobs (outbox)
                               └──[202 Accepted]

Outbox (x1) ⇄ Postgres (attachment_jobs.published_at IS NULL)
    │
    └──[XADD]→ Redis Streams (attachment.jobs)

Worker (x2) ⇄ Redis Streams (consumer group)
    ├──[SELECT ... FOR UPDATE SKIP LOCKED]→ Postgres (lease 60s)
    ├──[GET]→ staging/ → resize (thumb 256, crop 128, opt) →[PUT]→ final/
    ├──[INSERT variants + UPDATE ready]→ Postgres (транзакция)
    └──[XACK]→ Redis
  • Асинхронный приём (уровень 3): POST /api/v1/chats/{id}/attachments возвращает 202 Accepted сразу после того, как файл сохранён в staging, а в БД одной транзакцией записаны метаданные attachments (status=queued) и attachment_jobs (outbox). Это гарантирует, что после ответа 202 работа не потеряется при рестарте API.
  • Outbox (уровень 4): отдельный процесс cmd/outbox читает attachment_jobs WHERE published_at IS NULL и публикует в брокер. published_at ставится только после XADD. Падение между COMMIT и publish приводит к повторной публикации при следующем цикле; worker идемпотентен.
  • Брокер: Redis Streams (тот же Redis, AOF --appendonly yes). Consumer Group workers, XACK после durable-эффекта. В сообщении только job_id, attachment_id, pipeline_version, attempt (никаких URL или filename).
  • Worker (уровень 3-4): отдельный процесс, реплики 2. Забирает job через ClaimJobByID (lease 60s). Пишет original (server-side copy staging→final), thumbnail (256×256, fit), crop (128×128, center-cover) и optimized (JPEG q=70). Всё в одной транзакции с attachment_variants и status='ready'. XACK только после COMMIT.
  • Идемпотентность: ключ эффекта — (attachment_id, pipeline_version, variant). Повторная доставка того же job_id: MarkReady — no-op (если status='done'), attachment_variants — ON CONFLICT DO NOTHING. Также VariantsExist перед Claim.
  • Retry: RetryJob различает permanent (invalid_image → сразу failed) и transient (storage_error → backoff base * 2^(n-1) + jitter, max 5 попыток). Финальный failed с безопасным error_code.
  • Зависшие job: RequeueStuck в outbox и worker, каждые 30с: status='processing' AND lease_expires_at < now() → queued, published_at=NULL.
  • Replay: POST /api/v1/attachments/{id}/replay сбрасывает attempt=1, status='queued', published_at=NULL для failed-задач.
  • Очистка: MoveToFinal удаляет staging после CopyObject. ReconcileOrphans (в API) чистит attachment_gc и «зависшие» staging-объекты без job.

Что перенесено из lab4

  • PostgreSQL, Argon2id, sessions (с кэшем в Redis), горизонтальное масштабирование, Nginx.
  • Механизм идемпотентности idempotency_keys для сообщений.
  • S3-хранилище и приватный bucket, S3Store с таймаутами и ретраями.

Что изменено

  • Миграция 0002_attachments.sql: добавлены attachment_variants, attachment_jobs (outbox+lease), поля staging_key, pipeline_version, ready_at, failed_at. Таблица attachments теперь содержит status IN ('queued','processing','ready','failed').
  • UploadAttachment возвращает 202, статус queued; DownloadAttachment → 409 для не-ready.
  • Добавлены cmd/outbox, cmd/worker (обработка изображений, process.go).
  • src/domain/broker.go — обёртка Redis Streams.
  • compose.yaml: сервисы outbox (1 реплика) и worker (2 реплики), миграции вынесены в отдельный сервис migrate.
  • В attachments.go: EnqueueAttachment, ClaimJob, ClaimJobByID, MarkReady, RetryJob, RequeueStuck, ReplayFailed, MarkFailedPermanent, GetVariantKey, SelectUnpublishedJobs, MarkPublished.

Доказательства критериев

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Offline-структура и локальные refs make check PASS png
Полная OpenAPI 3.1 и JSON Schema make validate PYTHON=.venv/bin/python PASS png
Публичный smoke (lab5) make test PASS: 202, ready, thumbnail png
Persistence: перезапуск API+БД+Redis+S3 make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS png
Failover: остановка одной реплики API make test-failover ACTION_SCRIPT=scripts/stop-one.sh observed_instances_before: 2, successful_writes: 75, first_recovery: 5.371s png
Ур. 3: Upload → 202 → queued (worker не нужен) student_tests/states.py queued → ready, 3 варианта + original через ?variant=original txt
Ур. 3: Broker и worker — отдельные процессы docker compose ps outbox, worker-1, worker-2 png
Ур. 3: Статусы в API, лимиты и типы student_tests/limits.py 413, 415, 400 invalid_image txt
Ур. 3: original неизменен, thumbnail по контракту student_tests/variants.py byte-identical, thumbnail 256x160 (metadata matches), crop 128x128 txt
Ур. 3: Broker payload без filename/URL student_tests/broker-payload.py только id/version/attempt txt
Ур. 3: Очистка staging после ready student_tests/staging-cleanup.py staging object removed after ready txt
Ур. 3: Реестр failed (DLQ) student_tests/dlq.py invalid_image|1 txt
Ур. 3: Идемпотентность при повторной доставке student_tests/redelivery.py still 3 non-original variants txt
Ур. 4: Outbox закрывает разрыв COMMIT→publish student_tests/outbox.py published_at IS NULL при паузе outbox → ready после unpause txt
Ур. 4: Permanent error без retry student_tests/failed.py attempt=1, invalid_image — not retried txt
Ур. 4: Transient error → retry → ready student_tests/retry.py attempt=2, retry log lines: ... backoff=2s jitter=451ms txt
Ур. 4: Replay failed student_tests/replay.py replay -> queued, повторный permanent fail txt
Ур. 4: Lease / reaper зависших student_tests/lease.py reaper requeued the stuck job → ready txt
Ур. 4: Crash после side effect до ack student_tests/crash-before-ack.py recovery produced exactly 3 variants, no duplicates txt

Эксперименты и отказы

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Остановка одной реплики API 0 потерянных подтверждённых записей, LB переключается Failover PASS, 75 успешных сообщений 5.371 с, потерь нет
Рестарт API/БД/Redis/S3 (volumes) Вложение и сессия живы Persistence PASS ~30 с (запуск контейнеров), потерь нет
Отказ S3 API возвращает 503, worker ретраит retry.py PASS, attempt=2, backoff сработал После восстановления S3 — ready
Пауза outbox (разрыв COMMIT→publish) published_at=NULL, upload 202 outbox.py PASS, job дошёл до ready после unpause Задержка publish = период паузы, потерь нет
Пауза worker (зависший processing) Lease истекает, reaper возвращает в queued lease.py PASS, job вернулся в queued через ~60с + reaper ~90 с, потерь нет
SIGKILL worker во время processing Повторная доставка, без дублей вариантов crash-before-ack.py PASS, 3 варианта, без дублей ~100 с (lease + рестарт), потерь нет

Ограничения и следующие шаги

  • At-least-once: доставка Redis Streams + идемпотентный эффект ≠ exactly-once. При падении между XADD и MarkPublished возможна повторная публикация; повторный worker это корректно обрабатывает, но сообщение в Stream продублируется.
  • Replay доступен через endpoint POST /api/v1/attachments/{id}/replay (расширение сверх OpenAPI). В отчёте зафиксировано, что это не меняет семантику обязательных путей.
  • Optimized — JPEG q=70 вместо WebP (WebP-кодирование требует cgo-зависимостей, которых в alpine-сборке без CGO нет). Контракт допускает JPEG как «перекодированный» вариант; в отчёте явно указано.
  • Broker = Redis Streams вместо RabbitMQ — обосновано тем, что Redis уже нужен для кэша сессий, AOF включён, это уменьшает количество контейнеров. Если Redis упадёт без AOF-реплики, неопубликованные задачи будут ждать в attachment_jobs (outbox) — они не потеряются.
  • DLQ — пока реестр attachment_jobs.status='failed' + last_error_code, без отдельного UI. Для оператора — SELECT из БД и endpoint replay.
  • Не реализовано: версионирование нескольких pipeline (трек 5), auto-scaling worker’а по queue lag (трек 1), fault-injection с версионированием (трек 2). Уровень 5 не заявлен.
  • Нагрузка проверена только smoke + make test; полноценных замеров throughput/latency pipeline не делалось (не требуется для уровня 4).