18 KiB
Демонстрация — лабораторная 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
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}
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), пароли
# Регистрация: 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:
{"id":"...","username":"alice","display_name":"Алиса","created_at":"...Z"}
# Вход: ТОЛЬКО 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:
{"token":"<43 символа base64url>","token_type":"Bearer","expires_at":"...Z","user":{...}}
# Неверный пароль: 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 (в 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"
# Второй пользователь и чат (вызывающий обязан быть в 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: токен живёт только в памяти процесса, рестарт всех хранилищ
# Публичный 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 — показать, ЧТО перезапускалось):
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
# Тот же токен после рестарта: 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
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 и ошибки зависимостей
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):
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 сообщений)
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: согласованность кэша истории
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. Финальная регрессия (всё зелёное одним прогоном)
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 |
Завершение стенда
# Безопасная остановка: volumes сохраняются
docker compose down
# НАМЕРЕННОЕ удаление учебных данных: контейнеры И volumes (данные теряются)
docker compose down -v