# Демонстрация — лабораторная 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$$...`. **Что доказывает:** пароль хешируется библиотечным 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 — счётчик версии чата в Redis. - На каждый COMMIT записи (`CreateMessage`) выполняется `INCR chatver:`: старые ключи становятся «мёртвыми», следующее чтение строит ключ с новой версией → 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 ```