Files
mtusi2026lab5/src/DEMO2.md
T
2026-11-10 13:55:56 +03:00

18 KiB
Raw Blame History

Демонстрация — лабораторная 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