Files
mtusi2026lab2/REPORT.md
T
zemilesandClaude Opus 5.5 ffb98242ff ЛР 2: PostgreSQL, Bearer-сессии и кэш сессий в Valkey (на 4)
- Перенесён минимум lab1; переход 1 → 2: password при регистрации,
  Basic только на POST /auth/sessions, Bearer вместо X-User-Id, logout.
- PostgreSQL — источник истины: users, chats, chat_members, messages,
  sessions; миграции с PK/FK/UNIQUE/CHECK и индексами, атомарное
  создание чата, scrypt для паролей, SHA-256 токенов в БД.
- Valkey — кэш проверенных сессий с TTL, tombstone при logout,
  обход кэша и окно недоверия при отказе.
- Ограниченные пулы и таймауты PostgreSQL/Valkey, 503 при отказе БД.
- compose.yaml с Docker secrets и именованным томом, restart hook,
  собственные тесты, EXPLAIN на 110 тыс. сообщений, замер пользы кэша,
  заполненный REPORT.md и evidence/.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-16 02:15:02 +03:00

30 KiB
Raw Blame History

Отчёт — лабораторная 2

  • Автор, группа: Лазарев Юрий Сергеевич, БПИ2303
  • Целевая оценка; выбранный трек 5, если нужен: 4, трек 5 не заявлен
  • Commit/PR: TODO после публикации
  • Использованные источники, библиотеки и помощь ИИ: Python 3.12 (стандартная библиотека: http.server, hashlib.scrypt, secrets, hmac), psycopg[binary]==3.2.3, psycopg-pool==3.2.4, redis==5.2.1 (клиент протокола RESP, работает с Valkey); образы python:3.12.7-slim, postgres:16.4-alpine, valkey/valkey:8.0.2-alpine. Документация PostgreSQL (transactions, EXPLAIN, constraints), Valkey (persistence, eviction), RFC 7617. Код перенесён из моей lab1 и доработан с помощью ИИ-ассистента (Claude), проверен и запущен автором.

Запуск из чистого clone

Требования: Docker Engine 28 с Compose v2 (проверено: Docker Desktop 28.0.4, Compose v2.34.0, macOS), Python 3.9+ на хосте только для тестов, make. Порты 127.0.0.1:8080 и 127.0.0.1:8081 (тест TTL) должны быть свободны.

# 1. Локальные синтетические секреты и .env (значения не печатаются; повторный запуск ничего не перезаписывает)
sh scripts/init-secrets.sh            # или: make secrets
#    secrets/postgres_password, secrets/database_url, secrets/valkey.conf, secrets/cache_url (каталог в .gitignore)

# 2. Проверка конфигурации, сборка и запуск API + PostgreSQL + Valkey; --wait ждёт healthy
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait     # или: make up

# 3. Готовность
curl -si http://localhost:8080/health/ready             # 200 {"status": "ok"}

# 4. Публичные проверки
make check
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh

# 5. Собственные проверки: границы, гонка, откат, TTL, отказ БД, кэш и отказ Valkey, рестарт
docker compose --env-file .env --profile ttl up -d --wait api-short-ttl   # API с SESSION_TTL_SECONDS=2 на :8081
python3 student-tests/test_lab2.py --expiry-url http://localhost:8081 --db-outage --cache --persistence
docker compose --env-file .env --profile ttl stop api-short-ttl

# 6. План запроса истории на 110 000 сообщений + обход истории через API (добавляет синтетические данные)
python3 student-tests/history_bench.py --big 100000 --small-chats 20 --small-size 500

# 7. Польза кэша: транзакции PostgreSQL и задержка на 1000 проверок токена
python3 student-tests/cache_bench.py --label valkey
SESSION_CACHE=off docker compose --env-file .env up -d --wait api
python3 student-tests/cache_bench.py --label off
docker compose --env-file .env up -d --wait api          # вернуть кэш

Миграции применяются автоматически при старте API (каталог migrations/, таблица schema_migrations, advisory lock). Отдельный запуск без старта сервера:

docker compose --env-file .env run --rm api python /app/src/server.py --migrate-only

Безопасная остановка (данные и том сохраняются): docker compose --env-file .env --profile ttl down (или make down).

Намеренное удаление учебных данных (необратимо, удаляет том mtusi-lab2_pgdata): docker compose --env-file .env --profile ttl down -v. Если удалить secrets/, но оставить том, пароль в томе разойдётся с новым секретом — тогда нужно удалить и том.

Архитектура и решения

клиент (curl / tests)
   │  HTTP 127.0.0.1:8080, Basic только на POST /auth/sessions, далее Bearer
   ▼
api  (mtusi-messenger:lab2, Python 3.12, uid 10001, PID 1)
   │ 1) проверка токена: Valkey (кэш) ──промах/отказ──► 2) PostgreSQL
   ├──────────────► valkey (valkey:8.0.2-alpine) — кэш сессий, без persistence, пул ≤10, таймаут 250 мс
   ▼
postgres (postgres:16.4-alpine) — источник истины, пул ≤10, ожидание ≤5 с, statement_timeout 5 с
   └── volume pgdata → /var/lib/postgresql/data
Роль Service Образ/версия Health/readiness Volume Сеть/порт Credentials
api api сборка из Dockerfile, база python:3.12.7-slim HEALTHCHECK → /health/ready нет (stateless) 127.0.0.1:8080→8080 secrets database_url, cache_url → DATABASE_URL_FILE, CACHE_URL_FILE
postgres postgres postgres:16.4-alpine pg_isready pgdata (именованный) внутренняя сеть, 5432 secret postgres_password → POSTGRES_PASSWORD_FILE
redis_or_valkey valkey valkey/valkey:8.0.2-alpine valkey-cli ping (с паролем) нет: persistence выключено намеренно внутренняя сеть, 6379 secret valkey.conf (requirepass); без пароля — NOAUTH
api (TTL-тест) api-short-ttl, профиль ttl тот же образ — нет 127.0.0.1:8081→8080 те же секреты

Схема и транзакции (уровень 3)

Источник истины — PostgreSQL: пользователи, чаты, участники, сообщения и сессии. В памяти API состояния нет.

Схема (migrations/001_init.sql):

  • users: PK, UNIQUE (username), CHECK формата username и длины display_name; password_hash — scrypt.
  • chats: PK, CHECK длины title.
  • chat_members: PK (chat_id, user_id), FK на chats и users, position — порядок member_ids; индекс (user_id, chat_id) для списка чатов пользователя.
  • messages: PK, FK на чат и отправителя, CHECK 1–4000; индекс (chat_id, created_at, id) — обоснование ниже.
  • sessions: PK token_hash (SHA-256 токена), FK на users, expires_at, revoked_at; индекс expires_at.

Транзакционные границы:

  • Создание чата: проверка участников, INSERT chats и все INSERT chat_members — одна транзакция. Ошибка, включая нарушение FK, откатывает её целиком.
  • Сообщение: в одной транзакции SELECT ... FOR UPDATE строки чата с проверкой членства и INSERT. Вставки в один чат сериализуются, created_at = clock_timestamp() растёт в порядке фиксации, и keyset-курсор не пропускает конкурентные вставки. Ограничение: порядок зависит от часов сервера БД.
  • Регистрация: гонку одинакового username решает UNIQUE в БД (UniqueViolation → 409), без «SELECT, потом INSERT».
  • Миграции: каждый файл и его запись в schema_migrations — одна транзакция; процессы сериализуются pg_advisory_lock.

Аутентификация и сессии

  • Пароль 12–128 code points хешируется hashlib.scrypt (N=2^15, r=8, p=1, соль 16 байт). Проверка — hmac.compare_digest; для неизвестного username считается фиктивный хеш (одинаковое время ответа). bcrypt не выбран из-за усечения до 72 байт.
  • POST /api/v1/auth/sessions принимает только Basic. Любая ошибка — одинаковый 401 с WWW-Authenticate: Basic realm="messenger", charset="UTF-8".
  • Токен — secrets.token_urlsafe(32) (256 бит). В PostgreSQL и Valkey хранится только SHA-256 токена.
  • expires_at = now() + SESSION_TTL_SECONDS вычисляет БД; logout ставит revoked_at. Рестарт TTL не продлевает.
  • Остальные endpoint требуют Bearer; Basic и X-User-Id дают 401, X-User-Id рядом с Bearer игнорируется. Чужой и несуществующий чат одинаково дают 404.

Valkey: роль, источник истины, expiry и инвалидация (уровень 4)

Роль — кэш проверенных сессий (src/session_cache.py). Проверка Bearer-токена выполняется на каждом защищённом запросе, поэтому без кэша каждый запрос — это минимум одна транзакция PostgreSQL. Источник истины остаётся PostgreSQL, в Valkey лежат только производные копии:

  • ключ sess:<sha256(token) hex> — сам токен в Valkey не попадает;
  • значение {"user": {...}, "exp": <unix-время истечения сессии>} либо "revoked".

Путь проверки токена (current_user в src/server.py):

  1. GET sess:<h> в Valkey:
    • копия → пользователь, PostgreSQL не трогаем;
    • "revoked" → 401;
    • промах или ошибка → шаг 2.
  2. SELECT из sessions (действующая, не отозвана, не истекла). Затем SET sess:<h> ... PX=<ttl> NX.

Политика expiry:

  • Положительная запись живёт min(SESSION_CACHE_TTL_SECONDS=30, остаток сессии) (PX в мс), поэтому кэш не переживает сессию. При чтении exp дополнительно сверяется с часами.
  • Tombstone "revoked" живёт 31 с — дольше любой положительной записи.
  • maxmemory 64mb, allkeys-lru: вытеснение любой записи безопасно. Вытесненная копия означает промах и чтение из БД. Вытесненный tombstone тоже даёт промах, а БД отвечает «отозвана».

Инвалидация (logout):

  1. UPDATE sessions SET revoked_at — COMMIT в PostgreSQL.
  2. SET sess:<h> "revoked" поверх возможной копии (не DEL).

Кэш после промаха заполняется только через SET NX. Поэтому конкурентный запрос, прочитавший БД до отзыва, не может перезаписать tombstone. Кроме того, кэш не заполняется, если между чтением БД и записью прошло больше 1 с.

Persistence Valkey выключено намеренно (save "", appendonly no). Valkey — не единственное хранилище сессий, а кэш над PostgreSQL. После рестарта или FLUSHALL кэш пуст: сессии читаются из БД и снова кэшируются, действующие токены работают, отозванные остаются отозванными. Это проверено публичным persistence-тестом (restart hook перезапускает и Valkey) и тестом FLUSHALL.

Отказ Valkey:

  • Любая ошибка или таймаут (250 мс на соединение и операцию) → запрос обслуживается из PostgreSQL. Следующие 5 с кэш не опрашивается (circuit breaker), чтобы не платить таймаутом на каждом запросе.
  • /health/ready остаётся 200: Valkey не критичен для обязательного пути.
  • Если не удалось записать tombstone (Valkey завис или недоступен во время logout), процесс 31 с не доверяет положительным записям кэша. Устаревшая копия могла остаться в Valkey, но за это время она гарантированно истечёт.
  • Анонимный или неизвестный токен при отказе Valkey не проходит: решение всегда принимает PostgreSQL.

Ограничение: окно недоверия хранится в памяти процесса. В lab2 API один, и защита полная. В lab3 при нескольких репликах о неудавшейся инвалидации узнает только одна реплика. Тогда нужен общий сигнал (например, эпоха кэша в PostgreSQL) или отказ от logout при недоступном Valkey.

Пулы, таймауты, параметризация (уровень 4)

  • Все SQL-запросы параметризованы (%s в psycopg, значения отдельно от текста запроса). Ключи Valkey строятся из hex-хеша.
  • PostgreSQL: ConnectionPool(min_size=1, max_size=DB_POOL_SIZE=10, timeout=5), connect_timeout=5, statement_timeout=DB_STATEMENT_TIMEOUT_MS=5000. Перед выдачей соединение проверяется (check_connection), поэтому после рестарта БД нет ложных 503.
  • Valkey: BlockingConnectionPool(max_connections=10, timeout=0.25), socket_timeout и socket_connect_timeout 250 мс.
  • Нет БД → 503 unavailable за ≤5 с (ожидание пула и connect_timeout), а не зависание или 500.

Что перенесено из lab1 и что изменено

Из lab1 перенесён каркас HTTP-сервера на http.server: маршрутизация, единый формат ошибок, X-Request-Id, валидация полей и длин в code points, 415 для не-JSON, keyset-курсор с привязкой к ресурсу, логирование без тел запросов, SIGTERM, non-root образ.

Изменено (переход 1 → 2): password при регистрации; Basic → Bearer-сессия вместо X-User-Id; logout; in-memory хранилище заменено PostgreSQL (src/store.py); добавлены кэш сессий в Valkey (src/session_cache.py), миграции, Compose, Docker secrets, restart hook и собственные тесты.

Соответствие .env.example реальной конфигурации

Переменная Где используется Значение
APP_HOST, APP_PORT, APP_ENV src/server.py 0.0.0.0, 8080, lab
SESSION_TTL_SECONDS create_session 3600 (в api-short-ttl — 2)
DATABASE_URL_FILE database_conninfo /run/secrets/database_url
DB_POOL_SIZE, DB_STATEMENT_TIMEOUT_MS src/store.py 10, 5000
SESSION_STORE информационно: где хранятся сессии postgres (источник истины)
SESSION_CACHE cache_url() valkey; off отключает кэш (для сравнения)
CACHE_URL_FILE cache_url() /run/secrets/cache_url
SESSION_CACHE_TTL_SECONDS, CACHE_TIMEOUT_MS, CACHE_RETRY_SECONDS src/session_cache.py 30, 250, 5

Доказательства критериев

Уровень 3

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Структура skeleton make check PASS: offline skeleton structure... evidence/smoke.txt
Публичный smoke make test PASS: lab2 public API scenario evidence/smoke.txt
Данные и действующие сессии переживают рестарт API и всех хранилищ без удаления томов make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS; StartedAt у api, postgres и valkey изменился; в логах PostgreSQL shut down → ready to accept, у Valkey SIGTERM → Ready; том тот же evidence/persistence.txt
После рестарта отозванный токен остаётся отозванным, история та же test_lab2.py --persistence 5 × OK evidence/student-tests.txt
PK/FK, UNIQUE username, 4 таблицы \d таблиц ключи, users_username_key, CHECK, индексы evidence/database.txt
Миграции с нуля и повторно без дублей первый старт на пустом томе; --migrate-only × 2 migration applied: 001_init.sql; счётчики до и после равны evidence/database.txt
Создание чата атомарно чат с неизвестным 3-м участником 400, списки чатов не изменились, следующее создание — 201 evidence/student-tests.txt
Basic только на входе, Bearer на остальных, X-User-Id не даёт доступ тесты auth + smoke Basic на /users/me → 401; только X-User-Id → 401; владелец не меняется evidence/student-tests.txt
Срок жизни и отзыв TTL = 2; logout через 3 с 401; logout 204 → 401 → повторный 401 evidence/student-tests.txt
Password KDF users.password_hash все хеши scrypt N=2^15 r=8 p=1; в sessions только 32-байтовые SHA-256 evidence/database.txt
Secrets/volumes не в Git git status --ignored, git check-ignore .env и все файлы secrets/ игнорируются evidence/stack.txt

Уровень 4

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Valkey реально используется (кэш сессий с TTL) test_lab2.py --cache после входа в Valkey копия сессии; 50 запросов → 50 попаданий, 0 промахов evidence/student-tests.txt
Кэш осмысленный (снимает нагрузку с источника истины) cache_bench.py, 1000 проверок токена × 3 повтора транзакций PostgreSQL: 3–13 с кэшем против 1693–1789 без; p50 0,80–0,86 мс против 1,08–1,16 мс evidence/cache-bench.txt
Описаны источник истины, expiry, инвалидация раздел «Valkey» выше logout → tombstone, отозванный токен сразу 401 evidence/student-tests.txt
Рестарт/flush Valkey не теряет сессии (persistence не нужно: Valkey — кэш) FLUSHALL; restart hook действующий токен работает из БД, отозванный 401, кэш заново заполняется evidence/student-tests.txt, evidence/persistence.txt
Параметризованные запросы, ограниченный пул, таймауты код src/store.py, src/session_cache.py пулы ≤10, таймауты 5 с / 250 мс, statement_timeout раздел «Пулы» выше
Гонка регистрации одинакового username 20 параллельных POST /users ровно один 201, 19 × 409 evidence/student-tests.txt
Rollback составной операции чат с неизвестным участником ни чата, ни участников; следующее создание — 201 evidence/student-tests.txt
Индекс истории обоснован EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщений history_bench.py: 110 205 сообщений, один чат на 100 000 и 20 по 500 см. таблицу ниже: keyset-страница на глубине 90 000 — Index Scan, 51 строка, 7 буферов, 0,058 мс evidence/explain.txt
Пагинация не сканирует всю историю на каждой странице обход 100 000 сообщений через API, limit=100 1000 страниц без потерь и повторов; медиана первых 20 страниц 3,14 мс, последних 20 — 2,83 мс evidence/explain.txt
Автопроверка expiry при коротком TTL --expiry-url (TTL = 2) 200 → через 3 с 401 с WWW-Authenticate: Bearer evidence/student-tests.txt
Автопроверка logout и неверного пароля test_lab2.py logout 204/401/401; неверный пароль 401 Basic evidence/student-tests.txt
Автопроверка недоступности БД --db-outage ready 503, live 200, /chats 503 за <10 с, вход 503, неизвестный токен не проходит; после старта прежний токен работает evidence/student-tests.txt
Автопроверка недоступности Valkey --cache (stop valkey) ready 200; токен работает через БД за <2 с; без токена и с чужим 401; вход 201, logout 204 → 401; после старта токен, отозванный во время отказа, остаётся 401 evidence/student-tests.txt
Зависание Valkey во время logout не «воскрешает» токен --cache (pause valkey) logout 204; в Valkey осталась устаревшая копия, но через 6 с (breaker закрыт) токен всё равно 401; в журнале positive entries distrusted for 31s evidence/student-tests.txt

EXPLAIN (ANALYZE, BUFFERS) — сводка

Запрос — ровно тот, что выполняет приложение:

SELECT id, chat_id, sender_id, text, created_at FROM messages
WHERE chat_id = $1 AND (created_at, id) > ($2, $3)
ORDER BY created_at, id LIMIT 51

Данные: 110 205 строк, таблица 22 MB, индекс 11 MB; большой чат — 100 000 сообщений.

Вариант План Прочитано строк Буферов Время выполнения
Первая страница, индекс Index Scan messages_chat_order_idx 51 5 0,064 мс
Keyset после 90 000-го, индекс (как в приложении) Index Scan, условие ROW(created_at, id) > ROW(...) в Index Cond 51 7 0,058 мс
OFFSET 90000, индекс (так приложение не делает) Index Scan, затем отбрасывание 90 051 4 726 12,6 мс
Первая страница без индекса Parallel Seq Scan + Sort top-N вся таблица 2 836 12,3 мс
Keyset без индекса Seq Scan, Rows Removed by Filter: 100205 вся таблица 2 792 7,7 мс

Вывод: составной индекс (chat_id, created_at, id) совпадает с фильтром и сортировкой. Страница любой глубины — это спуск по B-дереву и чтение limit + 1 записей, без сортировки. Стоимость не зависит ни от глубины, ни от размера чата. OFFSET растёт линейно с глубиной, а без индекса каждая страница читает всю таблицу.

Стоимость индекса: 11 MB на 110 тыс. строк и дополнительная запись в B-дерево при каждой вставке. Заливка 110 тыс. строк с индексом заняла 1,8 с; отдельно стоимость записи на «4» не измерялась.

Ограничения замера: все страницы в shared buffers (shared hit), холодный кэш и диск не измерялись; один прогон на ноутбуке без лимитов CPU/RAM.

Эксперименты и отказы

Стенд: MacBook (macOS), Docker Desktop 28.0.4, лимиты CPU/RAM на контейнеры не заданы, настройки PostgreSQL и Valkey по умолчанию, кроме указанных выше. Замеры latency последовательные (один клиент), это не нагрузочный тест.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
scripts/restart.sh: штатный рестарт API, PostgreSQL и Valkey данные и сессии сохранены, прежний токен работает public persistence PASS; те же пользователь, чат и история; отозванный токен 401 ~3–4 с до ready; потерь нет; кэш пуст и заполняется заново
docker compose stop postgres ready 503, бизнес-запросы 503 за ограниченное время ready 503, live 200, /chats 503, вход 503; /users/me — 200 из кэша сессий, пока жива копия (≤30 с), иначе 503 (отзыв без БД невозможен: logout тоже 503) после start — несколько секунд; потерь нет
docker compose stop valkey API продолжает работать через PostgreSQL все операции работают, ready 200, ответ <2 с (одна попытка 250 мс, далее breaker 5 с) после start через 5 с кэш снова используется
FLUSHALL в Valkey кэш пуст, корректность сохранена действующий токен работает, отозванный 401 мгновенно
docker compose pause valkey во время logout отзыв фиксируется в БД, устаревшая копия не принимается logout 204; устаревшая копия в Valkey не принята (31 с недоверия) —
Сессия с SESSION_TTL_SECONDS=2 через 2 с — 401 401 на обоих экземплярах API (запись кэша живёт не дольше сессии) —

Гарантии durability: подтверждённое сообщение — это успешный COMMIT. При fsync=on и synchronous_commit=on (по умолчанию) WAL сброшен на диск до ответа, поэтому рестарт и падение процесса БД не теряют подтверждённых записей. Потерю тома или Docker-host это не покрывает.

Ограничения и следующие шаги

  • Выдерживается: рестарт или пересоздание контейнеров API, PostgreSQL и Valkey при сохранённом томе; временная недоступность PostgreSQL (503 и восстановление без перезапуска API); полная недоступность, зависание или очистка Valkey.
  • Не выдерживается: потеря тома или Docker-host (бэкапов нет); единственные экземпляры PostgreSQL, Valkey и API.
  • Окно недоверия кэшу после неудачной инвалидации локально для процесса; для нескольких реплик в lab3 нужен общий механизм (см. раздел «Valkey»).
  • Во время отказа PostgreSQL /users/me может быть отдан из кэша до 30 с — это осознанный выбор: копия соответствует действующей сессии, а отозвать её без БД нельзя.
  • HTTP без TLS допустим только на 127.0.0.1 с синтетическими данными.
  • Истёкшие и отозванные сессии не удаляются из таблицы автоматически (индекс sessions_expires_idx подготовлен для периодической очистки).
  • history_bench.py при каждом запуске добавляет ~110 тыс. синтетических сообщений в учебную БД.