- Перенесён минимум 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>
30 KiB
Отчёт — лабораторная 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: PKtoken_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):
GET sess:<h>в Valkey:- копия → пользователь, PostgreSQL не трогаем;
"revoked"→ 401;- промах или ошибка → шаг 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):
UPDATE sessions SET revoked_at— COMMIT в PostgreSQL.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_timeout250 мс. - Нет БД →
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 тыс. синтетических сообщений в учебную БД.