forked from mtusi2026/mtusi2026lab5
185 lines
18 KiB
Markdown
185 lines
18 KiB
Markdown
# Отчёт — лабораторная 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).
|