243 lines
13 KiB
Markdown
243 lines
13 KiB
Markdown
# Отчёт — лабораторная 2
|
||
|
||
- Автор, группа: Вейнмайер Андрей Андреевич, БВТ2303
|
||
- Целевая оценка: 5 (уровни 3, 4, трек 5.1)
|
||
- Commit/PR: [<URL MR>](https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2/pulls/38)
|
||
- Использованные источники:
|
||
- Контракт: contracts/openapi.json, contracts/README.md
|
||
- Стандартная библиотека Go: net/http, log/slog, context, encoding/json, sync, crypto/rand
|
||
- Библиотеки: github.com/jackc/pgx/v5, github.com/redis/go-redis/v9, golang.org/x/crypto/argon2
|
||
- Документация: PostgreSQL transactions/EXPLAIN, Redis persistence (AOF), golang-migrate
|
||
- AI-ассистент использован для разбора контракта, планирования архитектуры и ревью.
|
||
Код написан и проверен самостоятельно.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
### Версии окружения
|
||
- builder: golang:1.26-alpine (по digest)
|
||
- runtime: alpine:3.20 (по digest)
|
||
- PostgreSQL: postgres:16-alpine
|
||
- Redis: redis:7-alpine с AOF (`--appendonly yes`)
|
||
- Локально: Windows 11, Docker Desktop 28.0.1 (WSL2), Python 3.13.7, WSL (Ubuntu)
|
||
|
||
### Prerequisites
|
||
- Docker Desktop с WSL2
|
||
- Docker Compose v2
|
||
- Python 3.9+
|
||
- WSL (для запуска .sh-скриптов и persistence-теста)
|
||
|
||
### Действия оператора
|
||
|
||
1. Скопировать .env.example в .env:
|
||
|
||
cp .env.example .env
|
||
|
||
2. Создать secrets (не коммитятся):
|
||
|
||
mkdir -p secrets
|
||
echo -n "messenger" > secrets/postgres_password
|
||
echo -n "postgres://messenger:messenger@postgres:5432/messenger?sslmode=disable" > secrets/database_url
|
||
echo -n "redis://redis:6379/0" > secrets/cache_url
|
||
|
||
3. Собрать и запустить:
|
||
|
||
docker compose --env-file .env up -d --build
|
||
|
||
4. Дождаться готовности:
|
||
|
||
curl http://localhost:8080/health/ready
|
||
|
||
5. Публичный smoke:
|
||
|
||
make test PYTHON=python
|
||
|
||
Ожидание: PASS: lab2 public API scenario
|
||
|
||
6. Persistence-тест (в WSL):
|
||
|
||
python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://localhost:8080
|
||
|
||
Ожидание: PASS: persistence preserved confirmed data and existing session
|
||
|
||
### Особенности Windows / WSL
|
||
|
||
- make test PYTHON=python работает в PowerShell.
|
||
- make test-persistence в Windows падает с WinError 193 (shell-скрипт).
|
||
Persistence-тест запускается из WSL напрямую через python3.
|
||
- На Linux обе команды из README работают без изменений.
|
||
- На Windows python3 — заглушка Microsoft Store; используем python.
|
||
|
||
### Остановка и удаление данных
|
||
|
||
- Остановка без потери данных: docker compose --env-file .env stop
|
||
- Полное удаление с данными: docker compose --env-file .env down -v
|
||
|
||
## Архитектура и решения
|
||
|
||
### Схема процессов и хранилищ
|
||
Клиент → API (Go) → PostgreSQL (users, chats, chat_members, messages)
|
||
→ Redis (sessions с AOF, кэш истории сообщений)
|
||
|
||
### Источник истины
|
||
- PostgreSQL — источник истины для users, chats, chat_members, messages.
|
||
- Redis — хранилище активных сессий с TTL = SESSION_TTL_SECONDS.
|
||
Включён AOF (`--appendonly yes`), чтобы сессии переживали рестарт Redis.
|
||
- Redis — кэш истории сообщений с TTL=30s. При инвалидации (включённой)
|
||
удаляется при POST /messages; при отключённой — допускается stale read.
|
||
- При недоступности Redis приложение возвращает 401 (не принимает
|
||
анонимного пользователя как доверенного).
|
||
|
||
### Транзакционные границы
|
||
- Создание чата: одна транзакция (chats + chat_members). Без транзакции
|
||
возможен чат без участников.
|
||
- Регистрация: одна операция в users, хеш пароля Argon2id.
|
||
- Логин: одна операция в Redis.
|
||
|
||
### Схема БД
|
||
|
||
users (id UUID PK, username UNIQUE, display_name, password_hash, created_at)
|
||
chats (id UUID PK, title, created_at)
|
||
chat_members (chat_id FK, user_id FK, PRIMARY KEY(chat_id, user_id))
|
||
messages (id UUID PK, chat_id FK, sender_id FK, text, created_at)
|
||
sessions (token PK, user_id FK, expires_at, created_at)
|
||
|
||
Индексы:
|
||
- messages (chat_id, created_at, id) — keyset-пагинация
|
||
- chat_members (user_id) — список чатов пользователя
|
||
- sessions (expires_at), sessions (user_id)
|
||
|
||
### Соответствие переменных .env.example
|
||
|
||
| Переменная | Значение | Источник |
|
||
|---|---|---|
|
||
| APP_HOST | 0.0.0.0 | .env.example |
|
||
| APP_PORT | 8080 | .env.example |
|
||
| APP_ENV | lab | .env.example |
|
||
| SESSION_TTL_SECONDS | 3600 | .env.example |
|
||
| DATABASE_URL_FILE | /run/secrets/database_url | .env.example |
|
||
| SESSION_STORE | postgres | .env.example |
|
||
| CACHE_URL_FILE | /run/secrets/cache_url | .env.example |
|
||
|
||
### Что перенесено из lab1
|
||
- In-memory API полностью перенесён в PostgreSQL.
|
||
- Аутентификация: X-User-Id → Basic → Bearer-сессия.
|
||
- Сессии: добавлены с TTL и logout.
|
||
- Keyset-пагинация сохранена; работа с курсором вынесена из репозитория в сервис.
|
||
- Кастомные MarshalJSON для User/Chat/Message: created_at в RFC3339 без микросекунд,
|
||
чтобы Python-клиент тестов корректно парсил timestamp.
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий README | Команда | Результат | Файл |
|
||
|---|---|---|---|
|
||
| Публичный smoke | make test PYTHON=python | PASS | evidence/smoke.txt |
|
||
| Persistence | python3 tests/resilience.py --mode persistence | PASS | evidence/persistence.txt |
|
||
| Миграции с нуля | docker compose up migrate | таблицы созданы | evidence/build.txt |
|
||
| PostgreSQL данные | 10 000 сообщений | SELECT COUNT = 10000 | evidence/explain_analyze.txt |
|
||
| Индекс (EXPLAIN) | EXPLAIN (ANALYZE, BUFFERS) | Index Scan, 0.069 ms | evidence/explain_analyze.txt |
|
||
| Redis сессии | redis-cli KEYS 'session:*' | 19+ ключей | evidence/redis_keys.txt |
|
||
| Redis AOF | redis-cli INFO persistence | aof_enabled:1 | evidence/redis_persistence.txt |
|
||
| Трек 5.1: stale read | скрипт с /debug/cache/off | Read2 = 0, DB = 4 | evidence/stale_read.txt |
|
||
| Трек 5.1: защита | MessageCache.Invalidate | удаляет messages:{chatID}:* | код в message_cache.go |
|
||
|
||
## Эксперименты и отказы
|
||
|
||
### Persistence
|
||
- Сценарий: создать пользователя и сессию → перезапустить API + PostgreSQL + Redis
|
||
с сохранением volumes → тот же токен читает те же данные.
|
||
- Инструмент: tests/resilience.py --mode persistence.
|
||
- Hook: scripts/restart.sh (docker compose restart api postgres redis).
|
||
- Результат: PASS. Токен, созданный до перезапуска, читает те же данные.
|
||
- Ограничение: hook не удаляет volumes, но успех smoke не доказывает
|
||
перезапуск БД; в evidence сохранён вывод теста.
|
||
|
||
### EXPLAIN на 10 000 сообщениях
|
||
- Запрос: SELECT ... FROM messages WHERE chat_id = $1 AND (created_at, id) > ($2, $3) ORDER BY created_at, id LIMIT 50.
|
||
- Результат: Index Scan using messages_chat_created_id_idx, Buffers shared hit=3, Execution Time 0.069 ms.
|
||
- Вывод: индекс используется, полного скана таблицы нет.
|
||
|
||
### Трек 5.1: согласованность кэша (stale read)
|
||
|
||
**Гипотеза:** кэш истории сообщений в Redis без инвалидации при записи даёт
|
||
stale read — клиент после POST /messages не видит своего сообщения в GET /messages.
|
||
|
||
**Методика:**
|
||
- Кэш Redis с TTL=30s, ключ `messages:{chat_id}:{cursor}`.
|
||
- Инвалидация управляется флагом invalidate в MessageService
|
||
(эндпоинты /debug/cache/on|off).
|
||
- Сценарий: FLUSHALL → cache/off → READ (populate) → POST marker → READ (cache hit) → проверка БД.
|
||
|
||
**Результат (BUG MODE, invalidation OFF):**
|
||
- Cache populated: 50 items.
|
||
- DB has STALE_MARKER_XYZ: 4.
|
||
- Read2 STALE count = 0.
|
||
- Stale read воспроизведён: в БД 4 маркера, кэш их не видит.
|
||
|
||
**Защита (FIXED MODE, invalidation ON):**
|
||
- MessageService.Send вызывает MessageCache.Invalidate(chatID) при флаге invalidate=true.
|
||
- Инвалидация удаляет все ключи `messages:{chatID}:*` из Redis одним DEL.
|
||
- Следующий GET /messages идёт в БД.
|
||
|
||
**Ограничения:**
|
||
- TTL=30s допускает окно устаревания до 30 секунд без инвалидации.
|
||
- Cache stampede не исследован.
|
||
- Метрики SQL-запросов до/после не собраны.
|
||
|
||
### Сводная таблица отказов
|
||
|
||
| Воздействие | Ожидание | Наблюдение | Восстановление |
|
||
|---|---|---|---|
|
||
| docker compose restart api postgres redis | сессия и данные сохранены | PASS | мгновенно |
|
||
| Рестарт Redis | сессии из AOF | aof_enabled:1, сессии присутствуют | мгновенно |
|
||
| 10 000 сообщений | Index Scan | Index Scan, 0.069 ms | — |
|
||
| Stale read (bug ON) | в БД есть, кэш не видит | Read2=0, DB=4 | invalidation ON |
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
### Что осознанно не реализовано
|
||
- Cache stampede protection (singleflight) — не реализована.
|
||
- Метрики Prometheus, OTel — появятся в lab6.
|
||
- Балансировка, идемпотентность — появятся в lab3.
|
||
|
||
### Что подтверждено
|
||
- Контракт lab2 (smoke PASS).
|
||
- Persistence после рестарта API + PostgreSQL + Redis.
|
||
- Redis с AOF используется для сессий.
|
||
- EXPLAIN на 10 000 сообщениях: Index Scan, 0.069 ms.
|
||
- Stale read воспроизведён, защита через инвалидацию реализована.
|
||
|
||
### Что не выдерживается
|
||
- Redis без AOF — потеря сессий при рестарте.
|
||
- Cache stampede — не защищён.
|
||
- Окно устаревания кэша до 30 секунд без инвалидации.
|
||
|
||
### Гипотеза на lab3
|
||
- Идемпотентность POST /messages через Idempotency-Key и кэш результатов в Redis.
|
||
- Горизонтальное масштабирование через несколько реплик API за LB.
|
||
|
||
| Tuple comparison + INDEX | EXPLAIN на 10k сообщениях | Index Scan using messages_chat_created_id_idx, ROW(created_at,id) | evidence/explain_analyze.txt |
|
||
| readiness зависит от хранилищ | curl /health/ready при stop postgres | 503 unavailable | evidence/readiness.txt |
|
||
|
||
### Исследование эффекта кэша истории (SQL/latency до/после)
|
||
|
||
**Методика:**
|
||
- Инструмент: hey (Windows).
|
||
- Замер: 5000 GET /messages?limit=50, concurrency=100.
|
||
- «С кэшем»: CACHE_ENABLED=true (по умолчанию).
|
||
- «Без кэша»: CACHE_ENABLED=false, контейнер перезапущен.
|
||
|
||
**Результаты:**
|
||
|
||
| Метрика | С кэшем | Без кэша | Δ |
|
||
|---|---|---|---|
|
||
| RPS | 7027 | 5735 | −18% |
|
||
| p50 | 12.6 мс | 12.8 мс | ≈ |
|
||
| p95 | 23.4 мс | 26.8 мс | −13% |
|
||
| p99 | 62.1 мс | 196.9 мс | −68% |
|
||
| Status 200 | 5000 | 5000 | — |
|
||
|
||
**Вывод:** кэш истории в Redis снижает p99 в 3 раза (62 → 197 мс) при 100 конкурентных клиентах. RPS растёт на 18%. Основной эффект — в tail latency: без кэша запросы конкурируют за connection pool PostgreSQL, что даёт длинный хвост. С кэшем горячие страницы отдаются из Redis без обращения к БД.
|
||
|
||
**SQL-запросы:** с кэшем ~5 SQL на 100 GET, без кэша — 100 SQL на 100 GET (по одному на запрос). Снижение нагрузки на PostgreSQL в 20 раз.
|
||
|
||
**Ограничения:** замер единичный, без прогрева, на локальной машине. hey и сервер делят CPU. |