Files
mtusi2026lab2/REPORT.md
T
wh1tet3a e2532247cc
Application checks / application (pull_request) Canceled after 0s
Skeleton contracts / contracts (pull_request) Canceled after 0s
Record 80 HTTP tests and complete pre-submission verification
2026-11-07 08:51:38 +03:00

21 KiB
Raw Blame History

Лабораторная 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 и проверен:

SQL планы

Гипотеза чтения подтверждается. Цена — индекс примерно в 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 не публикуется и не содержит рабочих данных.

Вопросы защиты и ограничения

  1. Что подтверждает COMMIT? Транзакция завершена и видна следующим запросам согласно isolation. Проверены fsync=on, synchronous_commit=on, full_page_writes=on. WAL flush защищает штатный durability сценарий, но не потерю единственного диска/VM/host и не заменяет backup.
  2. Где сессии и что даст flush cache? Сессии в PG, в cache только User. Flush/restart cache даёт miss, но токен остаётся действующим; logout действует через PG независимо от TTL карточки.
  3. Auth против ACL? Сессия определяет пользователя. Отдельная проверка membership определяет доступ к чату; посторонний получает такой же 404, как отсутствующий ресурс. Успешный login сам по себе доступ не даёт.
  4. 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. Помощь ИИ использована при разборе требований, реализации, тестах и отчёте; измерения подтверждены сохранёнными запусками.