forked from mtusi2026/mtusi2026lab5
18 KiB
18 KiB
Отчёт — лабораторная 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 stagealpine:3.20— runtime stagepostgres: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 Groupworkers,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→ backoffbase * 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).