Lab5 - оценка 4

This commit is contained in:
2026-11-10 13:55:56 +03:00
parent 276dbdad8a
commit e138dfb13d
53 changed files with 7477 additions and 24 deletions
+312
View File
@@ -0,0 +1,312 @@
# Демонстрация — лабораторная 2 (PostgreSQL, сессии, Redis-кэш)
**Автор, группа:** BVT2304 Shiyan
**Целевая оценка:** 5 (уровни 3 + 4 + Трек 1 «Согласованность кэша»)
**Стенд:** Windows + Docker Desktop, PowerShell; все команды выполняются из корня репозитория.
**Секреты:** `.env` создаётся локально из `.env.example` и НЕ коммитится. Токены в командах ниже — подстановочные (`$T`), в Git не попадают.
Документ проводит защиту по сценарию README lab2: миграции к пустому volume → пользователи/вход/сообщение → persistence с токеном в памяти → expiry → роль Redis и ошибки зависимостей → план SQL → эксперимент трека 5. Каждый шаг: команда → ожидаемый вывод → что это доказывает.
---
## Шаг 0. Чистый старт: миграции к пустому volume
```powershell
cd C:\Users\maksimator\GolandProjects\mtusi2026lab2
# НАМЕРЕННОЕ удаление учебных данных (volume): доказываем, что схема строится с нуля
docker compose down -v
# Сборка и запуск всего стенда из репозитория
docker compose --env-file .env up -d --build
# Готовность: все три сервиса healthy
docker compose ps
# Миграции применились к пустому volume
docker compose logs api --tail 12
```
**Ожидаемый вывод:**
```
mtusi-api ... Up (healthy)
mtusi-postgres ... Up (healthy)
mtusi-redis ... Up (healthy)
{"level":"INFO","msg":"postgres connected"}
{"level":"INFO","msg":"running migration","file":"0001_init.sql"}
{"level":"INFO","msg":"redis connected"}
{"level":"INFO","msg":"server started","addr":"0.0.0.0:8080","pid":1}
```
```powershell
curl.exe -s http://localhost:8080/health/ready
curl.exe -s http://localhost:8080/health/live
```
Ожидаемо: `{"status":"ok"}` дважды.
**Что доказывает:** схема (users, chats, chat_members, messages, sessions + PK/FK/UNIQUE/индексы) создаётся версионируемой миграцией `0001_init.sql`, встроенной в бинарник (`go:embed`), к полностью пустому volume. Повторный рестарт не дублирует данные (`IF NOT EXISTS`).
---
## Шаг 1. Регистрация, вход (Basic → Bearer), пароли
```powershell
# Регистрация: password принимается ТОЛЬКО на входе (writeOnly)
Invoke-RestMethod -Uri http://localhost:8080/api/v1/users -Method Post -ContentType "application/json" -Body '{"username":"alice","display_name":"Alice","password":"Example-only-not-a-real-secret-123"}'
Invoke-RestMethod -Uri http://localhost:8080/api/v1/users -Method Post -ContentType "application/json" -Body '{"username":"bob","display_name":"Bob","password":"Example-only-not-a-real-secret-12773"}'
```
Ожидаемо: `201` и `User` БЕЗ полей password/password_hash:
```json
{"id":"...","username":"alice","display_name":"Алиса","created_at":"...Z"}
```
```powershell
# Вход: ТОЛЬКО Basic на /auth/sessions; ответ — opaque Bearer-токен
curl.exe -s -X POST -u "alice:Example-only-not-a-real-secret-123" http://localhost:8080/api/v1/auth/sessions
```
Ожидаемо: `201`:
```json
{"token":"<43 символа base64url>","token_type":"Bearer","expires_at":"...Z","user":{...}}
```
```powershell
# Неверный пароль: 401 + WWW-Authenticate: Basic (не раскрываем существование учётки)
curl.exe -s -i -X POST -u "alice:Wrong-password-999" http://localhost:8080/api/v1/auth/sessions
# Неизвестный пользователь: ТОТ ЖЕ ответ 401 + тот же заголовок
curl.exe -s -i -X POST -u "nosuchuser000:Example-only-not-a-real-secret-123" http://localhost:8080/api/v1/auth/sessions
# Пароль в БД: только хэш KDF, plaintext отсутствует
docker compose exec postgres psql -U messenger -d messenger -tAc "SELECT username, left(password_hash, 30) FROM users WHERE username='alice';"
```
Ожидаемо: оба входа → `HTTP/1.1 401` + `Www-Authenticate: Basic realm="messenger", charset="UTF-8"`; в БД строка вида `alice|scrypt$32768$8$1$<salt>$...`.
**Что доказывает:** пароль хешируется библиотечным password KDF (scrypt), не SHA-256 и не plaintext; неверные и неизвестные credentials неразличимы; токен непрозрачный (не username/UUID/JWT), энтропия 256 бит (32 байта `crypto/rand`).
---
## Шаг 2. Защищённый API: Bearer, доступ к чату, пагинация
```powershell
# Сохраняем токен в переменную PowerShell (в Git не попадает)
$s = curl.exe -s -X POST -u "alice:Example-only-not-a-real-secret-123" http://localhost:8080/api/v1/auth/sessions | ConvertFrom-Json
$T = $s.token
# Без токена: 401 + WWW-Authenticate: Bearer
curl.exe -s -i http://localhost:8080/api/v1/users/me
# X-User-Id с lab2 ИГНОРИРУЕТСЯ: доступа не даёт
curl.exe -s -i http://localhost:8080/api/v1/users/me -H "X-User-Id: $($s.user.id)"
# Basic на бизнес-endpoint: 401 + WWW-Authenticate: Bearer
curl.exe -s -i http://localhost:8080/api/v1/users/me -u "alice:Example-only-not-a-real-secret-123"
# С токеном: 200
curl.exe -s http://localhost:8080/api/v1/users/me -H "Authorization: Bearer $T"
```
```powershell
# Второй пользователь и чат (вызывающий обязан быть в member_ids)
$b = curl.exe -s -X POST http://localhost:8080/api/v1/users -H "Content-Type: application/json" -d "{\"username\":\"bob\",\"display_name\":\"Боб\",\"password\":\"Example-only-not-a-real-secret-123\"}" | ConvertFrom-Json
$bs = curl.exe -s -X POST -u "bob:Example-only-not-a-real-secret-123" http://localhost:8080/api/v1/auth/sessions | ConvertFrom-Json
$BT = $bs.token
$chat = curl.exe -s -X POST http://localhost:8080/api/v1/chats -H "Authorization: Bearer $T" -H "Content-Type: application/json" -d "{\"title\":\"Проект по ВНП\",\"member_ids\":[\"$($s.user.id)\",\"$($b.id)\"]}" | ConvertFrom-Json
# Сообщения и история (created_at, id) по возрастанию
curl.exe -s -X POST http://localhost:8080/api/v1/chats/$($chat.id)/messages -H "Authorization: Bearer $T" -H "Content-Type: application/json" -d "{\"text\":\"Привет, Боб!\"}"
curl.exe -s "http://localhost:8080/api/v1/chats/$($chat.id)/messages?limit=50" -H "Authorization: Bearer $BT"
# Посторонний (carol) получает 404, а не 403: существование чужого чата не раскрывается
$c = curl.exe -s -X POST http://localhost:8080/api/v1/users -H "Content-Type: application/json" -d "{\"username\":\"carol\",\"display_name\":\"Кэрол\",\"password\":\"Example-only-not-a-real-secret-123\"}" | ConvertFrom-Json
$cs = curl.exe -s -X POST -u "carol:Example-only-not-a-real-secret-123" http://localhost:8080/api/v1/auth/sessions | ConvertFrom-Json
curl.exe -s -i http://localhost:8080/api/v1/chats/$($chat.id) -H "Authorization: Bearer $($cs.token)"
```
Ожидаемо: `401` с `Www-Authenticate: Bearer realm="messenger"` в трёх негативных случаях; `200` с токеном; `201` на сообщения; история отсортирована; у carol — `404`.
**Что доказывает:** аутентификация (Bearer → сессия → пользователь) отделена от авторизации (участие в чате); списки содержат только доступные объекты; контракт ошибок соблюдён.
---
## Шаг 3. Persistence: токен живёт только в памяти процесса, рестарт всех хранилищ
```powershell
# Публичный persistence-тест: создаёт данные и сессию, держит токен в памяти,
# вызывает hook, после готовности читает ТЕ ЖЕ данные ТЕМ ЖЕ токеном
python tests/resilience.py --mode persistence --action-script scripts/restart.bat --base-url http://localhost:8080
```
Ожидаемо: `PASS: persistence preserved confirmed data and existing session.`
Ручное подтверждение объёма hook (требование tests/README.md — показать, ЧТО перезапускалось):
```powershell
docker compose ps # ДО: все healthy
scripts\restart.bat # hook: docker compose restart postgres redis api
docker compose ps # ПОСЛЕ: uptime сбросился, все healthy
docker volume ls | Select-String mtusi # volumes НЕ удалены: mtusi_postgres_data, mtusi_redis_data
docker compose logs api --tail 8 # shutdown signal received -> server stopped cleanly -> server started
```
```powershell
# Тот же токен после рестарта: 200 (сессия пережила рестарт, TTL не продлился)
curl.exe -s -o NUL -w "%{http_code}" http://localhost:8080/api/v1/users/me -H "Authorization: Bearer $T"
# Logout: 204 без тела; повтор с отозванным токеном: 401
curl.exe -s -o NUL -w "%{http_code}" -X DELETE http://localhost:8080/api/v1/auth/sessions/current -H "Authorization: Bearer $T"
curl.exe -s -i http://localhost:8080/api/v1/users/me -H "Authorization: Bearer $T"
```
Ожидаемо: `200`, затем `204`, затем `401` + `Www-Authenticate: Bearer realm="messenger"`.
**Что доказывает:** пользователи, чаты, сообщения и действительные сессии переживают перезапуск API и ОБОИХ хранилищ с сохранёнными volumes; источник истины — PostgreSQL (volume), API stateless.
---
## Шаг 4. Expiry при коротком TTL
```powershell
scripts\expiry.bat
```
Скрипт поднимает API с `SESSION_TTL_SECONDS=2`, прогоняет `student-tests/expiry_checks.py` и возвращает дефолтный TTL. Ожидаемо:
```
[PASS] login 201 with TTL=2
[PASS] fresh token 200
[PASS] expired token -> 401
[PASS] expired WWW-Authenticate Bearer
[PASS] re-login after expiry 201
EXPIRY CHECKS PASSED
```
**Что доказывает:** срок жизни сессии управляется `SESSION_TTL_SECONDS`; истёкший токен → 401 с корректным заголовком; TTL не продлевается рестартом.
---
## Шаг 5. Уровень 4: роль Redis и ошибки зависимостей
```powershell
python student-tests/failover_tests.py --base-url http://localhost:8080
```
Ожидаемо:
```
[PASS] redis down: ready stays 200 (cache optional)
[PASS] redis down: auth via postgres 200
[PASS] redis down: write 201
[PASS] redis down: read 200
[PASS] redis back: ready 200
[PASS] postgres down: ready becomes 503
[PASS] postgres down: protected request 503 (not 200/401)
[PASS] postgres down: anonymous still 401
[PASS] postgres back: ready 200
[PASS] postgres back: same session valid 200
ALL FAILOVER TESTS PASSED
```
**Роль Redis (для защиты):** кэш сессий и кэш истории; источник истины — PostgreSQL. Политика expiry: TTL кэш-ключа сессии = остаток `expires_at`; инвалидация при logout и при истечении. Политика инвалидации истории: версия чата в ключе кэша (Шаг 7). При потере Redis приложение деградирует в SQL (warn в логах), не отказывает и НЕ принимает анонимный запрос как доверенный: при потере Postgres защищённый запрос → 503, аноним → 401.
Дополнительно — гонка регистрации и rollback составной операции (уровень 4):
```powershell
python student-tests/run_tests.py --base-url http://localhost:8080
```
Ключевые строки: `[PASS] race registration: one 201, rest 409` (UNIQUE-ограничение детерминированно решает гонку), `[PASS] rollback: no partial chat` (транзакция создания чата атомарна).
---
## Шаг 6. Уровень 4: план SQL (EXPLAIN ANALYZE BUFFERS, ≥10k сообщений)
```powershell
scripts\explain_demo.bat
Get-Content scripts\explain_plans.md
```
Сев 10 000 сообщений (итого 30 002 в чате), `ANALYZE`, два плана одного keyset-запроса:
| Метрика | С индексом `messages_history_idx` | Без индекса |
|---|---|---|
| План | `Index Scan using messages_history_idx`, Index Cond: `chat_id AND ROW(created_at,id) > ROW(...)` | `Seq Scan on messages` (30 002 строк) + `Sort` |
| Buffers | `shared hit=4 read=1` | `shared hit=383` |
| Execution Time | **0.118 ms** | **4.613 ms** |
**Что доказывает:** индекс `(chat_id, created_at, id)` покрывает запрос пагинации; страница читает только нужные строки, полный scan истории на страницу не выполняется.
---
## Шаг 7. Уровень 5, Трек 1: согласованность кэша истории
```powershell
scripts\cache_demo.bat
Get-Content evidence\cache_track.md
```
Эксперимент переключает `CACHE_MODE` и перезапускает API; четыре фазы:
| Фаза | Смысл | Ключевой результат |
|---|---|---|
| `off` | baseline: кэша нет | `reads=100 sql=132 stampede_sql=32` — 32 конкурентных холодных чтения = 32 SQL (stampede не ограничен) |
| `naive` | кэш БЕЗ инвалидации | `[PASS] naive: stale read OBSERVED` — прогретый кэш вернул страницу БЕЗ только что записанного сообщения (проблема показана) |
| `versioned` | защита: версия чата в ключе + single-flight | `[PASS] read-after-write OK`; `stampede_sql=1` (32 холодных чтения схлопнуты в один SQL); `reads=100 sql=0` (тёплые чтения из кэша) |
| `recovery` | `docker compose restart redis` | сессия валидна (источник истины Postgres), история читается, read-after-write OK, `sql_after_restart=1` (кэш перестроился) |
**Механика защиты (для защиты):**
- Ключ кэша истории: `hist:v<N>:<chat>:<cursor>:<limit>`, где N — счётчик версии чата в Redis.
- На каждый COMMIT записи (`CreateMessage`) выполняется `INCR chatver:<chat>`: старые ключи становятся «мёртвыми», следующее чтение строит ключ с новой версией → cache miss → свежий SELECT. Stale read исключён конструктивно, а не «удалением ключей».
- Single-flight: при конкурирующих miss одного ключа в SQL идёт ровно один запрос, остальные ждут его результат (защита от stampede без глобальной блокировки).
- Контрактное требование «кэш не возвращает устаревшую историю после успешной записи» выполнено в режиме `versioned` и проверено тестом.
---
## Шаг 8. Финальная регрессия (всё зелёное одним прогоном)
```powershell
python tests/smoke.py --base-url http://localhost:8080 # контракт
python student-tests/run_tests.py --base-url http://localhost:8080 # 46 проверок
python student-tests/failover_tests.py --base-url http://localhost:8080
scripts\expiry.bat
scripts\cache_demo.bat
python tests/resilience.py --mode persistence --action-script scripts/restart.bat --base-url http://localhost:8080
```
Ожидаемые финальные строки: `PASS: lab2 public API scenario...`, `ALL STUDENT TESTS PASSED`, `ALL FAILOVER TESTS PASSED`, `EXPIRY CHECKS PASSED`, четыре `PHASE ... DONE`, `PASS: persistence preserved...`.
---
## Артефакты демонстрации
| Артефакт | Что доказывает |
|---|---|
| `docker compose logs api` (migration + shutdown/startup) | миграции с нуля, идемпотентность, graceful shutdown |
| `scripts/explain_plans.md` | индекс истории обоснован EXPLAIN (ANALYZE, BUFFERS) на 30 002 сообщениях |
| `evidence/cache_track.md` + `evidence/phase_*.txt` | эксперимент трека 5: stale read, stampede, SQL-счётчики до/после, recovery |
| Вывод `tests/resilience.py` + `docker compose ps` до/после + `docker volume ls` | persistence hook действительно перезапустил API и оба хранилища, volumes сохранены |
| Вывод `student-tests/failover_tests.py` | деградация при Redis down; 503 при Postgres down; аноним не доверен |
| Вывод `student-tests/run_tests.py` | контрактные коды/заголовки, гонка регистрации, rollback, пагинация, logout |
| Вывод `scripts/expiry.bat` | expiry при коротком TTL |
| `git status` / `.gitignore` | `.env` и секреты не в Git |
---
## Завершение стенда
```powershell
# Безопасная остановка: volumes сохраняются
docker compose down
# НАМЕРЕННОЕ удаление учебных данных: контейнеры И volumes (данные теряются)
docker compose down -v
```