21 KiB
Лабораторная 2 — PostgreSQL, сессии и Valkey
Автор: Маслов, БВТ2301. Цель: 5, трек 2 «План запроса и восстановление».
Ветка solution/bvt2301-maslov; основа — skeleton ЛР2, ветка master.
Публикации и удалённого CI пока нет.
Воспроизводимый запуск
Нужны Docker 25+ с BuildKit/Compose v2+, make, Git и uv 0.13.7.
Python 3.14.7; FastAPI 0.143.3, Pydantic 2.14.1, Uvicorn 0.54.0,
psycopg 3.3.6, psycopg-pool 3.3.3, argon2-cffi 25.1.0, redis client 8.1.0.
Точные транзитивные версии — uv.lock. Базовые образы Python/uv,
PostgreSQL 18.3 и Valkey 8.1.3 закреплены тегами и digest.
uv sync --locked
make bootstrap
make check validate PYTHON=.venv/bin/python
make lint
make up
NO_PROXY=localhost,127.0.0.1 no_proxy=localhost,127.0.0.1 make test
make test-student
NO_PROXY=localhost,127.0.0.1 no_proxy=localhost,127.0.0.1 \
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make verify
uv run --locked python -m scripts.verify_pool --output evidence/pool-repeat.json
API: http://127.0.0.1:8082. PostgreSQL/Valkey не публикуют host-порты.
Для другого порта задать PUBLIC_PORT в окружении и передавать BASE_URL
проверкам. Все повторные evidence должны иметь новые имена файлов;
для make доступны VERIFY_OUTPUT и RESEARCH_OUTPUT.
make down останавливает стенд, сохраняя PostgreSQL volume. Его повторный
запуск использует прежние данные и секреты. Намеренное удаление только
учебных данных данного проекта: docker compose down --volumes.
Не применять к рабочим данным и не запускать глобальный Docker prune.
Bootstrap создаёт только отсутствующие .env/secret files. Каталог secrets
имеет 0700, файлы доступны non-root контейнеру через read-only file mounts.
Не пересоздавать пароль при сохранённом PG volume: initdb уже создал роль
со старым паролем. В Git/образ секреты и .env не попадают.
Конфигурация: APP_HOST/APP_PORT — bind внутри API; PUBLIC_PORT — Compose; DATABASE_URL_FILE/CACHE_URL_FILE — пути к файловым секретам; SESSION_TTL_SECONDS — абсолютный срок сессии (default 3600); DB_POOL_SIZE — 1…32 (default 10). SESSION_STORE=postgres и APP_ENV в example информационные: реализация не переключает источник истины этими строками. Compose передаёт приложению только нужные ему настройки и секреты.
Архитектура и перенос
Из своей ЛР1 перенесены HTTP-контракт, строгие схемы, ошибки/request ID, ACL, UUID/UTC, cursor и собственные HTTP-тесты. Сохранены неизменёнными README/COURSE/contracts/tests текущего skeleton. Git-история ЛР1 не переносилась; репозиторий ЛР2 независим.
flowchart LR
C[HTTP клиент] --> API[FastAPI: JSON, auth, request ID]
API --> T[Ограниченный threadpool: сервисные операции]
T --> PG[(PostgreSQL: данные и сессии)]
T --> V[(Valkey: карточка User, TTL 30 s)]
M[Одноразовый migrate] --> PG
SQL parameter binding используется для всех данных клиента. Динамические идентификаторы в research — через psycopg.sql.Identifier и проверенный UUID-префикс; в рабочем API пользователь не задаёт имена таблиц/SQL.
Модель и транзакции заданы до SQL в PLAN.md:
| Объект/операция | Ограничения и граница |
|---|---|
| users | UUID PK, UNIQUE username; KDF до получения соединения; INSERT атомарен |
| chats + members | FK, уникальный участник/позиция; чат и все участники в одной транзакции |
| messages | FK(chat_id,sender_id) на members; INSERT подтверждается после COMMIT |
| sessions | PK digest32bytes, FK user, created_at/expires_at; raw token не хранится |
| history | (chat_id,created_at,id), tuple keyset + LIMIT limit+1 |
| migrations | SQL-файлы, checksum и advisory lock; отдельный сервис до API |
Миграции с нуля и повторное применение не создают пользовательские данные. Изменение применённого файла отклоняется; добавляется новая миграция. API сам схему не создаёт. Отказ migrate блокирует запуск API в Compose.
Пул на процесс: min 1 / max 10, ожидание 1 с; connect_timeout 2 с; statement_timeout 2.5 с, lock_timeout 1 с, idle transaction timeout 6 с. Общий клиентский срок операций на выданном соединении — 4 с, включая замороженный сервер. При таймауте соединение закрывается и не возвращается в пул как исправное. SQL, KDF и cache I/O не блокируют ASGI event loop. Liveness не обращается к БД; readiness проверяет PostgreSQL, не Valkey.
Пароли, сессии и кэш
- Argon2id: 64 MiB, t=3, p=4. Одновременно не больше двух KDF на процесс, ожидание слота ограничено 5 с. UTF-8 пароль 12–128 code points обрабатывается целиком, без усечения/нормализации. Проверено 127 emoji и двоеточие.
- Basic — только POST auth/sessions; собственный строгий base64/UTF-8 parser, разделение по первому двоеточию. Неизвестный username проходит dummy KDF, возвращается тот же 401. Хэш/пароль не входят в UserDTO и HTTP-ошибки.
- Токен — secrets.token_urlsafe(32), 256 бит энтропии; PostgreSQL хранит только SHA-256 digest случайного токена. Это не password KDF и не JWT.
- Каждый запрос проверяет сессию и абсолютный expires_at в PostgreSQL. Logout удаляет сессию; прежний cache hit не оживляет её. X-User-Id игнорируется, Basic на бизнес-endpoint даёт 401. WWW-Authenticate соответствует Basic/Bearer. Restart срок не продлевает.
- Valkey хранит только неизменяемую карточку User, TTL 30 с, maxmemory 64 MiB, allkeys-lru; persistence выключена, собственного volume нет. Ошибка cache — miss и чтение PG, backoff 5 с; socket/connect timeout 0.15 с, скрытые retry отключены. При отказе PG cached User не авторизует запрос.
- API не изменяет карточки пользователей, поэтому инвалидации при записи не требуется. При восстановлении старого snapshot вне API кэш надо очистить. История вообще не кэшируется: read-after-write идёт из PG.
Образы API: non-root UID10001, exec Python PID1, healthcheck, read-only rootfs, tmpfs и cap_drop=ALL. Лимиты API 1 CPU/512 MiB, PG 1 CPU/512 MiB, cache 0.25 CPU/128 MiB. Логи JSON: request ID/маршрут/код/время; без тел, Authorization, паролей, токенов, их digest и параметров SQL.
Таблица доказательств
| Критерий README | Команда | Факт / evidence |
|---|---|---|
| API ЛР1 + новый auth | make test, make test-student |
Smoke PASS, 80 passed; clean-clone-pre-pr.json |
| Данные и прежний токен после restart всех stores | make test-persistence, make verify |
public-persistence.txt, lifecycle.json; CID/PID/StartedAt до/после |
| PK/FK/UNIQUE и атомарный чат | migrations, регистрационная гонка, injected rollback | 001_core.sql, lifecycle.json; после сбоя строка чата отсутствует |
| Версионируемые миграции и bootstrap | make verify, clean clone |
Повтор без изменений, секреты сохранены, checksum mismatch отклонён; clean-clone.json |
| Реальная роль Valkey | make verify |
20 cache hits, stop/flush не теряют данные/сессию |
| Parameter binding, bounded pool и timeouts | python -m scripts.verify_pool, make verify |
pool.json: pool1, ожидание 1.005 с →503; pause PG4.011 с →503 |
| Индекс, EXPLAIN ≥10k | make research |
90 планов для 5 размеров чата; query-plan.json |
| Expiry, logout, неверный пароль, отказы | HTTP-тесты, lifecycle | TTL2s →401; stop cache →200; stop PG →503; logout →401 |
| Трек2: ≥100k, индексы/запись/backup | research | 101110 сообщений, 2 индекса, 3 повтора, восстановление и сверка |
| Независимый clean clone | python scripts/verify_clean.py |
Полный PASS с новыми секретами/volumes, 80 passed; clean-clone-pre-pr.json |
Первая проверка не утверждает наличие карточки в cache непосредственно перед PG fault без дополнительного EXISTS: границы evidence. Финальный вариант проверил это и неизменность expires_at.
Финальный чистый clone
Последняя проверка перед PR: source commit
5e7c93a0362e667551c8807a674fe04927b20e53.
Новые .env, секреты и volumes; pinned image build; check/validate/lint;
публичный smoke; 80 passed за 93.23 с; public persistence; lifecycle,
pool и checksum guard — PASS. Повторно выполнено исследование: 101110
сообщений, 90 EXPLAIN-планов, backup/restore snapshot совпал.
Хэши runtime-модулей совпали; image revision соответствует source commit.
Все временные containers/volumes этого clone удалены, рабочий volume сохранён.
Первая попытка clean-clone проверки остановилась на persistence: Docker сменил автоматически назначенный host-порт при restart, а тест сохранил прежний BASE_URL. Смена подтверждена на том же контейнере (65424 → 65441). Проверка исправлена выбирать свободный фиксированный номер порта один раз; код API/сессий не менялся. Первая попытка не выдана за успешную: описание, диагностика. Прежний полный повтор — clean-clone.json. Последний повтор перед PR — clean-clone-pre-pr.json.
После проверенного source commit менялись только отчёт, шаблон и evidence; runtime src, зависимости, Dockerfile и Compose остались теми же. Добавлен отдельный application workflow для CI; наличие файла не означает его запуска на Gitea. Публикация, fork/MR и удалённый CI пока не выполнялись.
Повторная сверка выполнена по текущим README, COURSE, contracts/tests
и handoff от 30.10.2026. Все уровни 3/4 и выбранный трек 2 покрыты
таблицей доказательств. Исходные задание, контракт и публичные тесты
сохранены. Исправлены два пограничных дефекта: JSON принимается только
в UTF-8, десятичный limit=0001 допустим. Три регрессионных теста сначала
упали на прежнем образе, затем прошли в новом чистом clone:
исходные отказы.
При повторе также проверены неизменность абсолютного срока сессии,
наличие User в cache перед каждым отказом PG (503 за 4.044/0.011 с),
pool timeout 1.006 с, rollback, checksum миграции и backup/restore.
Исследовательские числа ниже относятся к исходному сохранённому
query-plan.json; новый clean clone независимо повторил методику и сверку,
но его timings не подставлялись в старые таблицы.
Исследование: методика и результаты
Гипотеза в PLAN закоммичена до замера. Стенд: Apple M1, 8 CPU, 8 GiB RAM, Docker Desktop 4.98.0/Engine29.9.2; PostgreSQL в контейнере 1 CPU/512 MiB. Рабочие таблицы messenger не меняются: создаются research_UUID и restored_UUID именно данного запуска, затем удаляются вместе с временным dump.
SQL seed: 5 чатов 90000/10000/1000/100/10, всего101110 сообщений; уникальные тексты80ASCII. Seed обходит HTTP, это явно исследовательский набор, а не нагрузка регистрации/Argon2. Схема и migration metadata соответствуют приложению; исследовательский пользователь не используется для входа. Данных других людей нет.
Сравниваются chat_id-only и (chat_id,created_at,id). На каждом варианте
VACUUM ANALYZE и прогрев; head/middle/tail каждой истории, LIMIT 51,
EXPLAIN ANALYZE BUFFERS. Три повтора с порядком A/B, B/A, A/B; custom plans,
prepared statements в эксперименте отключены. Подготовительный OFFSET
применяется только для получения контрольной границы вне измеряемого
запроса; рабочая пагинация использует только keyset.
| Индекс | SQL middle90k, мс | Буферы | Размер, bytes | INSERT+COMMIT1000, мс | WAL, bytes |
|---|---|---|---|---|---|
| chat_id | 7.237 | 2209 | 729088 | 37.53 | 347536 |
| keyset | 0.017 | 5 | 5980160 | 11.55 | 427672 |
Это медианы трёх повторов; min/max и остальные размеры/позиции — query-summary.csv, полные планы — query-plan.json. График построен из raw и проверен:
Гипотеза чтения подтверждается. Цена — индекс примерно в 8.2 раза больше и больший WAL на запись. Рост именно времени INSERT не подтвердился: в этом опыте keyset быстрее и на записи. Причину этого различия отдельный профиль не устанавливал. WAL — глобальный PG-счётчик; фон и cache state могут влиять. EXPLAIN execution time не называется HTTP latency или CPU time.
Backup pg_dump -Fc: 3026259 bytes, 0.480 с; restore в новую БД: 0.664 с. Сверены count всех 6 таблиц, SHA-256 всей истории и 15 полных сообщений. После snapshot специально сделан ещё один SQL COMMIT: в источнике 101111, в восстановленной копии 101110. Это демонстрация границы snapshot/RPO, не измерение потери HTTP-подтверждений и не универсальный RTO сервиса. Пик PG cgroup с момента старта контейнера 266039296 bytes (включает подготовку и прочие проверки); это не RSS отдельного процесса и не пик только SELECT.
uv run --locked python -m research.query_plan --output evidence/query-plan-repeat.json
uv run --locked python -m research.analyze evidence/query-plan-repeat.json
Запускать последовательно с проверками отказов. Сырые результаты не перезаписываются; dump не публикуется и не содержит рабочих данных.
Вопросы защиты и ограничения
- Что подтверждает COMMIT? Транзакция завершена и видна следующим запросам согласно isolation. Проверены fsync=on, synchronous_commit=on, full_page_writes=on. WAL flush защищает штатный durability сценарий, но не потерю единственного диска/VM/host и не заменяет backup.
- Где сессии и что даст flush cache? Сессии в PG, в cache только User. Flush/restart cache даёт miss, но токен остаётся действующим; logout действует через PG независимо от TTL карточки.
- Auth против ACL? Сессия определяет пользователя. Отдельная проверка membership определяет доступ к чату; посторонний получает такой же 404, как отсутствующий ресурс. Успешный login сам по себе доступ не даёт.
- KDF и checksum? Человеческий пароль имеет ограниченную энтропию, поэтому нужен дорогой Argon2id с солью. Случайный 256-битный токен можно индексировать быстрым SHA-256 digest; checksum backup решает проверку целостности данных, а не защиту пароля.
Один PG/cache/API на host — не HA. Нет TLS на внешнем маршруте, стенд только loopback и синтетические данные. PG init-role владеет учебной БД и имеет широкие права; production разделение SQL-ролей не заявляется. Backup snapshot не сохраняет последующие сообщения/отзывы сессий; без WAL-архива и recovery policy это неизбежное ограничение восстановления. POST сообщения ЛР2 не идемпотентен: после неизвестного исхода COMMIT автоматический retry может создать дубль; это задача ЛР3.
Источники и помощь
README/COURSE/contracts/tests преподавателя; справочные методические наборы; PostgreSQL, Psycopg, Argon2, Valkey, FastAPI/Pydantic/Uvicorn. Поведение client timeout дополнительно сверено с установленным кодом psycopg3.3.6 и реальной паузой PostgreSQL. Помощь ИИ использована при разборе требований, реализации, тестах и отчёте; измерения подтверждены сохранёнными запусками.
