Files
mtusi2026lab2/DEMO.md

27 KiB
Raw Permalink Blame History

Демонстрация лабораторной 2 на защите

Сценарий повторяет раздел «Сценарий защиты» из README: стек поднимается с нуля на пустом volume, затем показываются сессии, сохранность после рестарта, роль Valkey, план SQL и отказы зависимостей.

Важно: выполняйте команды по порядку в одном окне терминала. Переменные B, S, ALICE, BOB, CAROL, CHAT, TA, TB, TC и функции j, pg, vk живут только в этом окне.


0. Подготовка: чистый clone

Если запущен рабочий стенд, останавливаем его. Volume при этом сохраняется, порт 8080 освобождается:

(cd ~/Desktop/вуз/ВНП/lab2/mtusi2026lab2 && docker compose --profile ttl-test down)

Скачиваем решение в новую папку:

git clone -b solution/bvt2304-koshelev ssh://git@gitea.privcloud.tech:2222/Iicon18/mtusi2026lab2.git ~/Desktop/lab2-demo
cd ~/Desktop/lab2-demo

Отдельное имя compose-проекта даёт отдельные контейнеры и новый пустой volume:

export COMPOSE_PROJECT_NAME=lab2-demo
cp .env.example .env

Если порт 8080 или 8081 занят, поменяйте APP_PORT / SHORT_TTL_PORT в .env, следующая команда сама подхватит новые значения.

B=http://127.0.0.1:$(sed -n 's/^APP_PORT=//p' .env); S=http://127.0.0.1:$(sed -n 's/^SHORT_TTL_PORT=//p' .env); echo "$B $S"

Вспомогательные функции: достать поле из JSON, выполнить SQL, выполнить команду Valkey.

j() { python3 -c 'import sys,json;print(json.load(sys.stdin)[sys.argv[1]])' "$1"; }
pg() { docker compose exec -T postgres psql -U messenger -d messenger -c "$1"; }
vk() { docker compose exec -T valkey sh -c 'valkey-cli --no-auth-warning -a "$(sed -n "s/^requirepass //p" /run/secrets/valkey_conf)" "$@"' valkey-cli "$@"; }

Сказать: «Это свежий clone моей ветки в отдельный compose-проект, база будет пустой. .env и секреты не хранятся в Git, создаю их локально».


1. Секреты

make secrets
ls -l secrets/
git check-ignore -v secrets/database_url .env

Сказать:

  • «scripts/init-secrets.sh генерирует случайные пароли PostgreSQL и Valkey в папку secrets/. Она в .gitignore, поэтому в репозиторий не попадает».
  • «В контейнеры пароли приходят как compose secrets, файлами в /run/secrets/..., а не переменными окружения. Поэтому их не видно в docker inspect».
  • «Приложение читает DATABASE_URL_FILE и CACHE_URL_FILE, то есть путь к файлу, а не сам пароль».

2. Запуск стека и миграции

cat compose.yaml

Сказать:

  • «Четыре сервиса: postgres — источник истины, valkey — кэш сессий, migrate — одноразовый запуск миграций, api — приложение».
  • «Версии образов закреплены: postgres:17.6-alpine3.22, valkey/valkey:8.1.4-alpine3.22; latest нигде нет».
  • «depends_on с условиями: api стартует, только когда postgres healthy, а migrate завершился с кодом 0».
  • «Данные PostgreSQL лежат в именованном volume pgdata».
  • «Порт api опубликован только на 127.0.0.1, порты БД и Valkey наружу не публикуются».
make up
docker compose ps --all
docker compose logs migrate
curl -si "$B/health/ready"

Сказать:

  • «make up = docker compose up -d --build --wait, ждёт, пока healthcheck api станет healthy. Healthcheck api проверяет /health/ready, а readiness делает SELECT 1 в PostgreSQL».
  • «migrate в статусе Exited (0): применил 0001_init на пустую базу (1 applied now, 0 before)».

3. Схема БД

pg '\dt'
pg '\d messages'
pg 'SELECT * FROM schema_migrations'

Сказать:

  • «Таблицы users, chats, chat_members, messages, sessions и служебная schema_migrations, где записаны применённые миграции».
  • «UNIQUE(username), CHECK на формат и длины».
  • «Внешний ключ messages (chat_id, sender_id) → chat_members: база сама не даст записать сообщение от не-участника».
  • «Индекс messages_chat_history_idx (chat_id, created_at, id) повторяет запрос истории, обоснование в шаге 12».
  • «Миграции версионируются. Раннер берёт pg_advisory_lock и пропускает уже применённые версии, поэтому повторный запуск безопасен».

4. Публичный тест

make check
make test BASE_URL="$B"

Сказать: «Это публичный smoke-тест преподавателя для lab2: регистрация с паролем, вход через Basic, работа по Bearer, чаты, сообщения, пагинация, ошибки и logout».


5. Регистрация, вход, общий чат

Регистрация теперь требует password (12–128 символов):

ALICE=$(curl -s -X POST "$B/api/v1/users" -H 'Content-Type: application/json' -d '{"username":"alice","display_name":"Алиса","password":"Alice-demo-pass-1"}' | tee /dev/stderr | j id)
BOB=$(curl -s -X POST "$B/api/v1/users" -H 'Content-Type: application/json' -d '{"username":"bob","display_name":"Боб 🚀","password":"Bob-demo-pass-123"}' | tee /dev/stderr | j id)
CAROL=$(curl -s -X POST "$B/api/v1/users" -H 'Content-Type: application/json' -d '{"username":"carol","display_name":"Кэрол","password":"Carol:with:colons"}' | tee /dev/stderr | j id)

Сказать: «В ответе нет ни пароля, ни хеша, только id, username, display_name, created_at. Время назначает PostgreSQL».

Пароль в базе хранится только как хеш:

pg "SELECT username, left(password_hash, 40) AS hash FROM users WHERE username IN ('alice','bob','carol')"

Сказать: «Хеш Argon2id, строка начинается с $argon2id$v=19$m=65536,t=3,p=4: 64 МБ памяти и 3 прохода на одну проверку. Соль своя у каждого пароля, поэтому одинаковые пароли дают разные хеши».

Вход: Basic только на POST /auth/sessions. curl -u сам собирает заголовок Authorization: Basic base64(username:password):

curl -si -X POST -u 'carol:Carol:with:colons' "$B/api/v1/auth/sessions"
TA=$(curl -s -X POST -u 'alice:Alice-demo-pass-1' "$B/api/v1/auth/sessions" | j token); TB=$(curl -s -X POST -u 'bob:Bob-demo-pass-123' "$B/api/v1/auth/sessions" | j token); TC=$(curl -s -X POST -u 'carol:Carol:with:colons' "$B/api/v1/auth/sessions" | j token); echo "длина токена: ${#TA}"

Сказать:

  • «Ответ 201: token, token_type: Bearer, expires_at, user. Двоеточие в пароле допустимо, потому что строка делится по первому :».
  • «Токен — secrets.token_urlsafe(32), 256 случайных бит. Он непрозрачный: внутри нет ни id, ни username, это не JWT».
  • «Срок жизни из SESSION_TTL_SECONDS (по умолчанию 3600 с), expires_at считает база».

В базе лежит не сам токен, а его sha256:

pg "SELECT encode(token_hash,'hex') AS token_hash, expires_at, revoked_at FROM sessions ORDER BY created_at DESC LIMIT 3"

Сказать: «Если украдут дамп БД, войти по нему не получится: из sha256 токен не восстановить. Медленный KDF для токена не нужен: он случайный, 2^256 вариантов не перебрать. Пароль же выбирает человек, его можно перебрать по словарю, поэтому для пароля нужен медленный Argon2id».

Алиса создаёт чат с Бобом, оба пишут:

CHAT=$(curl -s -X POST "$B/api/v1/chats" -H 'Content-Type: application/json' -H "Authorization: Bearer $TA" -d "{\"title\":\"Проект по ВНП\",\"member_ids\":[\"$ALICE\",\"$BOB\"]}" | tee /dev/stderr | j id)
curl -s -X POST "$B/api/v1/chats/$CHAT/messages" -H 'Content-Type: application/json' -H "Authorization: Bearer $TA" -d '{"text":"Привет, Боб! 👋"}'
curl -s -X POST "$B/api/v1/chats/$CHAT/messages" -H 'Content-Type: application/json' -H "Authorization: Bearer $TB" -d '{"text":"Привет, Алиса!"}'
curl -s "$B/api/v1/chats/$CHAT/messages" -H "Authorization: Bearer $TB" | python3 -m json.tool --no-ensure-ascii

Сказать:

  • «Чат и участники создаются одной транзакцией. Если участник неизвестен, FK срабатывает внутри транзакции, вставка чата откатывается и клиент получает 400. Полупустого чата не остаётся (проверяет db_integrity_test.py)».
  • «sender_id сервер берёт из сессии. Сообщение вставляется одним запросом INSERT … WHERE EXISTS (участник): проверка доступа и запись атомарны».

Кэрол аутентифицирована, но не участник чата:

curl -i "$B/api/v1/chats/$CHAT/messages" -H "Authorization: Bearer $TC"

Сказать: «Аутентификация отвечает на вопрос "кто ты": токен Кэрол валиден. Доступ отвечает на вопрос "можно ли тебе в этот чат": нельзя, поэтому 404, а не 403, чтобы не раскрывать, что такой чат существует».


6. Ошибки аутентификации

Неверный пароль и несуществующий пользователь дают одинаковый 401 с вызовом Basic:

curl -i -X POST -u 'alice:wrong-password-1' "$B/api/v1/auth/sessions"
curl -i -X POST -u 'nobody:wrong-password-1' "$B/api/v1/auth/sessions"

Сказать: «Ответы одинаковые, поэтому подобрать существующие username не выйдет. Для несуществующего пользователя всё равно проверяется фиктивный хеш, чтобы время ответа тоже было одинаковым».

Basic на бизнес-endpoint даёт 401 с вызовом Bearer:

curl -i -u 'alice:Alice-demo-pass-1' "$B/api/v1/users/me"

X-User-Id из lab1 больше ничего не значит:

curl -i "$B/api/v1/users/me" -H "X-User-Id: $ALICE"
curl -s "$B/api/v1/users/me" -H "Authorization: Bearer $TC" -H "X-User-Id: $ALICE"

Сказать: «Без токена X-User-Id даёт 401. С токеном Кэрол и X-User-Id Алисы ответ — Кэрол: заголовок просто игнорируется».

Короткий пароль при регистрации даёт 400:

curl -i -X POST "$B/api/v1/users" -H 'Content-Type: application/json' -d '{"username":"dave","display_name":"Дэйв","password":"short"}'

7. Роль Valkey: кэш сессий

Все ключи сессий: сколько секунд осталось жить и значение.

for k in $(vk --scan --pattern 'session:*'); do echo "$(vk TTL "$k")s  $(vk GET "$k" | cut -c1-70)"; done

Сказать:

  • «Строки {"user": …} — закэшированные живые сессии. Строки revoked — tombstone'ы после logout, например от smoke-теста в шаге 4 (подробно в шаге 9)».
  • «Источник истины — PostgreSQL. Valkey только кэширует проверку токена, чтобы не ходить в БД на каждом запросе. /users/me вообще обслуживается из кэша».
  • «Ключ — session: + sha256 токена, значение — пользователь и expires_at».
  • «TTL записи = min(остаток сессии, 300 с). При чтении из кэша expires_at сравнивается ещё раз, поэтому просроченная сессия из кэша не пройдёт».
  • «Persistence у Valkey выключена (save "", appendonly no). После flush или рестарта кэш просто пуст: следующий запрос проверит токен в PostgreSQL и снова положит его в кэш. Данные при этом не теряются».

8. Сохранность: рестарт API и всех хранилищ

cat scripts/restart.sh
docker compose ps --format 'table {{.Service}}\t{{.Status}}'
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL="$B"
docker compose ps --format 'table {{.Service}}\t{{.Status}}'

Сказать: «Тест держит токен только в памяти, вызывает мой restart.sh (остановить api, valkey и postgres, затем поднять заново, volume не трогается) и тем же токеном читает те же данные. По Up N seconds видно, что все три контейнера действительно перезапускались».

Проверим руками тем же токеном Алисы:

vk DBSIZE
curl -s "$B/api/v1/chats/$CHAT/messages" -H "Authorization: Bearer $TA" | python3 -m json.tool --no-ensure-ascii
docker compose logs migrate | tail -1

Сказать:

  • «Прежний токен работает, сообщения на месте. Сессия пережила рестарт, потому что хранится в PostgreSQL. Срок не продлился: expires_at записан в базе».
  • «Старые записи кэша пропали вместе с рестартом Valkey. Те несколько ключей, что видны в DBSIZE, заново положили проверочные запросы теста после рестарта: кэш наполняется сам из PostgreSQL».
  • «Миграции при рестарте прогнались ещё раз: 0 applied now, 1 before, без дублирования».
  • «Ответ на вопрос "что подтверждает COMMIT": запись попала в WAL и сброшена на диск (fsync=on, synchronous_commit=on по умолчанию). Поэтому 201 после COMMIT означает, что сообщение переживёт и падение PostgreSQL. Если выключить synchronous_commit, последние подтверждённые транзакции можно потерять».

9. Logout

curl -i -X DELETE "$B/api/v1/auth/sessions/current" -H "Authorization: Bearer $TC"
curl -i "$B/api/v1/users/me" -H "Authorization: Bearer $TC"
curl -i -X DELETE "$B/api/v1/auth/sessions/current" -H "Authorization: Bearer $TC"
for k in $(vk --scan --pattern 'session:*'); do echo "$k => $(vk GET "$k" | cut -c1-40)"; done

Сказать:

  • «Logout даёт 204 без тела. После него тот же токен получает 401, повторный logout тоже 401».
  • «Порядок такой: сначала revoked_at в PostgreSQL (источник истины), потом в Valkey пишется tombstone revoked, а не простое удаление ключа».
  • «Зачем tombstone: параллельный запрос мог прочитать сессию из БД до logout и положить её в кэш после. Кэш заполняется через SET NX и не перезапишет tombstone, поэтому отозванная сессия не воскреснет».

10. Истечение сессии (короткий TTL)

Поднимаем второй экземпляр того же образа с SESSION_TTL_SECONDS=2:

docker compose --profile ttl-test up -d --wait api-short-ttl

Вход и обе проверки одной строкой: окно в 2 секунды слишком короткое, чтобы успеть вставить отдельные команды.

TD=$(curl -s -X POST -u 'bob:Bob-demo-pass-123' "$S/api/v1/auth/sessions" | tee /dev/stderr | j token); echo; curl -s -o /dev/null -w 'сразу: %{http_code}\n' "$S/api/v1/users/me" -H "Authorization: Bearer $TD"; sleep 3; curl -si "$S/api/v1/users/me" -H "Authorization: Bearer $TD"
docker compose --profile ttl-test stop api-short-ttl

Сказать: «expires_at всего через 2 секунды после входа. Сразу 200, через 3 секунды 401 с WWW-Authenticate: Bearer, хотя запись была и в кэше. Обычный api работает с TTL 3600, так как smoke требует не меньше 300».


11. Отказы зависимостей

Valkey недоступен — API работает без кэша

docker compose stop valkey
curl -si "$B/health/ready"
time curl -s "$B/api/v1/users/me" -H "Authorization: Bearer $TA"
curl -s -o /dev/null -w '%{http_code}\n' "$B/api/v1/users/me" -H "Authorization: Bearer $TC"
docker compose logs --tail 3 api
docker compose start valkey

Сказать:

  • «Readiness 200: Valkey для API не критичен».
  • «Запросы идут напрямую в PostgreSQL, ответ за миллисекунды. Остановленный контейнер сразу отказывает в соединении. Если бы сеть зависла, сработал бы таймаут 0.3 с. После первой ошибки circuit breaker 5 секунд вообще не обращается к Valkey, поэтому задержка не копится. В логе предупреждение bypassing cache».
  • «Отозванный токен Кэрол по-прежнему 401: отзыв записан в БД».

PostgreSQL недоступен — ограниченная ошибка, анонимного доступа нет

Заранее берём новый токен Боба. Проверок по нему ещё не было, поэтому в кэше его нет:

TB2=$(curl -s -X POST -u 'bob:Bob-demo-pass-123' "$B/api/v1/auth/sessions" | j token)
docker compose stop postgres
curl -si "$B/health/live"; echo; curl -si "$B/health/ready"
curl -si "$B/api/v1/chats" -H "Authorization: Bearer $TA"
curl -s -o /dev/null -w '%{http_code}\n' "$B/api/v1/users/me" -H "Authorization: Bearer $TB2"; curl -s -o /dev/null -w '%{http_code}\n' "$B/api/v1/users/me"

Сказать:

  • «Liveness 200: процесс жив. Readiness 503: обслуживать запросы безопасно нельзя».
  • «Бизнес-запрос даёт 503 unavailable мгновенно, без SQL и стектрейсов в теле. Pool ограничен 10 соединениями, таймауты подключения, захвата соединения и команды — 3, 3 и 5 с, так что зависнуть запрос не может».
  • «Токен, который проверить негде (в кэше его нет, БД лежит), получает 503, а не 200: непроверенный запрос не считается аутентифицированным. Без токена — по-прежнему 401».
docker compose start postgres
until curl -s -o /dev/null -w '%{http_code}' "$B/health/ready" | grep -q 200; do sleep 0.5; done; echo ready
curl -s "$B/api/v1/users/me" -H "Authorization: Bearer $TB2"

Сказать: «API восстановился сам, без своего рестарта: pool переподключается к базе по требованию».


12. Индекс истории и EXPLAIN

make explain
cat evidence/explain_history.txt

Сказать:

  • «Скрипт засевает 70 000 синтетических сообщений, 20 000 из них в одном чате, и выполняет тот же запрос, что в коде, как prepared statement: WHERE chat_id = $1 AND (created_at, id) > ($2, $3) ORDER BY created_at, id LIMIT 51».
  • «С индексом (chat_id, created_at, id): Index Scan, условие по курсору уходит прямо в Index Cond, читается 4 буфера, около 0.03 мс. Даже на глубокой странице после 15 000-го сообщения работа та же».
  • «Без индекса (DROP INDEX внутри транзакции и ROLLBACK): Seq Scan по всей таблице и Sort, 940 буферов, 3–4 мс, и время растёт вместе с таблицей».
  • «Keyset против OFFSET: OFFSET 15000 заставил бы прочитать и выбросить 15 000 строк на каждой странице. Курсор сразу прыгает в нужное место индекса».

13. Уровень 4: свои тесты одной командой

make test-student BASE_URL="$B" SHORT_TTL_URL="$S"

Сказать:

  • own_tests.py, concurrency_test.py — перенесены из lab1: битый JSON, чужой чат, пустое сообщение, пагинация; 100 параллельных сообщений от 10 клиентов.
  • auth_test.py — неверный пароль, Basic и X-User-Id на бизнес-endpoint, пароль с : и UTF-8, logout только текущего токена, истечение при TTL=2 с.
  • db_integrity_test.py:
    • 20 параллельных регистраций одного username → ровно один 201 и девятнадцать 409. Гонку решает UNIQUE в БД, а не проверка "SELECT, потом INSERT";
    • rollback создания чата;
    • Argon2id в базе;
    • повторные миграции ничего не меняют.
  • dependency_test.py — роль Valkey (кэш, TTL, tombstone), остановка Valkey, остановка PostgreSQL и восстановление.
  • sigterm_test.sh — docker compose stop api → код выхода 0, а не 137.

14. Остановка и удаление данных

Обычная остановка: данные остаются в volume.

docker compose --profile ttl-test down
docker volume ls | grep lab2-demo

Намеренное удаление учебных данных демо-стенда (необратимо):

docker compose --profile ttl-test down -v

Сказать: «down удаляет контейнеры, но не volume, поэтому данные переживут и это. Только down -v удаляет volume. В restart.sh и тестах -v не используется нигде».


Короткие ответы на вопросы из README

  • Что подтверждает COMMIT и от чего зависят гарантии.
    • COMMIT значит, что транзакция записана в WAL и, при synchronous_commit=on и fsync=on (по умолчанию), сброшена на диск. Такая запись переживает падение процесса и рестарт ОС.
    • С synchronous_commit=off последние подтверждённые транзакции можно потерять. С fsync=off после сбоя питания можно повредить базу.
    • Потерю самого диска или хоста COMMIT не покрывает: нужны реплики и бэкапы.
  • Где хранятся сессии и что будет после flush или рестарта Redis.
    • Сессии хранятся в PostgreSQL, в таблице sessions (sha256(token), expires_at, revoked_at). Valkey только кэш.
    • После flush кэш пуст, первая проверка токена идёт в БД. Ни одна сессия не теряется и не воскрешается: отзыв тоже записан в БД. Поэтому persistence у Valkey не нужна.
  • Аутентификация против доступа к чату.
    • Аутентификация устанавливает, кто ты: валидный Bearer-токен, иначе 401.
    • Доступ (авторизация) решает, можно ли этому пользователю к этому ресурсу: участник ли он чата. Если нет — 404, а не 403, чтобы не раскрывать существование чата.
  • Hash пароля против быстрого checksum.
    • Быстрый хеш (sha256) нужен для целостности и для индексации случайных значений: так мы храним токены.
    • Пароль низкоэнтропийный, его подбирают по словарю. Для него нужен медленный KDF с солью и затратами памяти (Argon2id), чтобы каждая попытка подбора была дорогой даже на GPU.