Files
mtusi2026lab2/REPORT.md
T
Weinmaier_Andrew 24fe6e23d2
Skeleton contracts / contracts (pull_request) Canceled after 0s
lab2: add missing evidence from benchmark
2026-10-10 08:06:11 +03:00

243 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 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.