# Отчёт — лабораторная 5 - Автор, группа: Морозова Ольга Андреевна, БВТ2303 - Целевая оценка: **4** (треки на 5 не заявлены) - Commit/PR: TODO после публикации - Использованные источники: [README.md](README.md), [COURSE.md](COURSE.md), [contracts/openapi.json](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) ### Подготовка ```sh 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 ``` ### Сборка и запуск ```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` - желаемое количество реплик. ### Тесты ```sh 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) ```sh docker compose --env-file .env down --remove-orphans ``` ### Намеренное удаление учебных данных ```sh docker compose --env-file .env down --remove-orphans -v rm -f secrets/*.txt ``` ## Архитектура и решения ```text 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](evidence/2_Tests_Passing.png) | | Полная OpenAPI 3.1 и JSON Schema | `make validate PYTHON=.venv/bin/python` | PASS | [png](evidence/2_Tests_Passing.png) | | Публичный smoke (lab5) | `make test` | PASS: 202, ready, thumbnail | [png](evidence/2_Tests_Passing.png) | | Persistence: перезапуск API+БД+Redis+S3 | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS | [png](evidence/2_Tests_Passing.png) | | Failover: остановка одной реплики API | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | `observed_instances_before: 2`, `successful_writes: 75`, `first_recovery: 5.371s` | [png](evidence/2_Tests_Passing.png) | | **Ур. 3:** Upload → 202 → queued (worker не нужен) | `student_tests/states.py` | queued → ready, 3 варианта + original через `?variant=original` | [txt](evidence/my_tests_passing.txt) | | **Ур. 3:** Broker и worker — отдельные процессы | `docker compose ps` | `outbox`, `worker-1`, `worker-2` | [png](evidence/1_Healthcheck.png) | | **Ур. 3:** Статусы в API, лимиты и типы | `student_tests/limits.py` | 413, 415, 400 invalid_image | [txt](evidence/my_tests_passing.txt) | | **Ур. 3:** original неизменен, thumbnail по контракту | `student_tests/variants.py` | `byte-identical`, `thumbnail 256x160 (metadata matches)`, `crop 128x128` | [txt](evidence/my_tests_passing.txt) | | **Ур. 3:** Broker payload без filename/URL | `student_tests/broker-payload.py` | только id/version/attempt | [txt](evidence/my_tests_passing.txt) | | **Ур. 3:** Очистка staging после ready | `student_tests/staging-cleanup.py` | `staging object removed after ready` | [txt](evidence/my_tests_passing.txt) | | **Ур. 3:** Реестр failed (DLQ) | `student_tests/dlq.py` | `invalid_image\|1` | [txt](evidence/my_tests_passing.txt) | | **Ур. 3:** Идемпотентность при повторной доставке | `student_tests/redelivery.py` | `still 3 non-original variants` | [txt](evidence/my_tests_passing.txt) | | **Ур. 4:** Outbox закрывает разрыв COMMIT→publish | `student_tests/outbox.py` | `published_at IS NULL` при паузе outbox → ready после unpause | [txt](evidence/my_tests_passing.txt) | | **Ур. 4:** Permanent error без retry | `student_tests/failed.py` | `attempt=1, invalid_image — not retried` | [txt](evidence/my_tests_passing.txt) | | **Ур. 4:** Transient error → retry → ready | `student_tests/retry.py` | `attempt=2`, `retry log lines: ... backoff=2s jitter=451ms` | [txt](evidence/my_tests_passing.txt) | | **Ур. 4:** Replay failed | `student_tests/replay.py` | `replay -> queued`, повторный permanent fail | [txt](evidence/my_tests_passing.txt) | | **Ур. 4:** Lease / reaper зависших | `student_tests/lease.py` | `reaper requeued the stuck job` → `ready` | [txt](evidence/my_tests_passing.txt) | | **Ур. 4:** Crash после side effect до ack | `student_tests/crash-before-ack.py` | `recovery produced exactly 3 variants, no duplicates` | [txt](evidence/my_tests_passing.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).