20 KiB
Отчёт — лабораторная 2
Автор: Горбанюк, БВТ2301. Целевая оценка: 5, трек 2 «План запроса и восстановление». Подготовлено локально 17.10.2026.
Публичный форк: https://gitea.privcloud.tech/Wemiliam/mtusi2026lab2. Ветка решения: solution/bvt2301-gorbanyuk, целевая ветка преподавателя — master. Ветка опубликована; МР преподавателю: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2/pulls/138.
Запуск из чистого clone
Нужны Docker с Compose v2+ и make. Для собственных тестов и исследования: Python 3.14.7 и uv 0.12.13. Образы: Python 3.14.7-slim-bookworm с digest из Dockerfile, PostgreSQL 18.3, Valkey 8.1.3-alpine. В uv.lock закреплены 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 и транзитивные зависимости.
git switch solution/bvt2301-gorbanyuk
make bootstrap
docker compose --env-file .env config --quiet
make up
NO_PROXY=localhost,127.0.0.1 no_proxy=localhost,127.0.0.1 make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
Bootstrap один раз создаёт случайные credentials учебной БД, secret files и .env. Существующие значения сохраняет. Секреты читаются из файлов, не печатаются, не включаются в образ и Git. Родительский secrets/ имеет права 0700; файлы доступны non-root процессу через Compose bind-mount secrets.
Старт: PostgreSQL healthy → migrate → API healthy. Повтор migrate сверяет checksum и не дублирует DDL/данные. Make up ждёт готовности. API слушает 0.0.0.0:8080, с хоста доступен только http://127.0.0.1:8082. БД и кэш по умолчанию не публикуют порты хоста. Для интеграционных проверок:
uv sync --locked
VCS_REF=$(git rev-parse HEAD) docker compose --env-file .env \
-f compose.yaml -f compose.test.yaml up -d --build --wait
make check validate PYTHON=.venv/bin/python
make lint test-student
uv run --locked python scripts/verify_lifecycle.py --output evidence/lifecycle-repeat.json
uv run --locked python research/query_plan.py --output evidence/query-plan-repeat.json
Override открывает только localhost:55432/56379. Собственные тесты создают отдельную временную БД student_tests_, исследование — research_ и restored_*. Рабочая messenger не очищается; в finally удаляются только созданные проверками БД. Для новых результатов выбираются новые имена JSON.
make down # обычная остановка своего стенда: данные остаются
# Только для намеренного удаления ВСЕХ учебных данных lab2:
docker compose --env-file .env down --volumes
Удаление volumes не входит в проверки или restart hook. После обычного down/up нужны прежние secrets и volume. Удаление secret files при сохранённом volume не меняет пароль уже созданной БД.
Архитектура и транзакции
Перенесены собственные HTTP-слой, схемы, сервисы, immutable domain values и cursor из lab1. In-memory repository заменён PostgreSQL; X-User-Id заменён Basic → Bearer. README, COURSE, CONTRIBUTING, contracts и публичные tests текущего skeleton сохранены.
Клиент → один API → PostgreSQL; Valkey — восстанавливаемый кэш карточки владельца сессии. Таблицы, ограничения и транзакционные границы зафиксированы в SCHEMA.md. Миграция задаёт PK/FK, UNIQUE username, порядок участников, составной FK автора сообщения в участников и индекс истории (chat_id,created_at,id).
Значения SQL параметризованы. Имена таблиц в исследовании оформляются psycopg.sql.Identifier. Pool: максимум 8 соединений, 32 ожидающих; ожидание 1 с, connect timeout 2 с, statement_timeout 2500 мс, lock_timeout 1000 мс. Соединение проверяется перед выдачей. Ошибка зависимости превращается в безопасный 503 без SQL и credentials.
Каждая запись подтверждается после COMMIT. Создание чата и участников — одна транзакция: ошибочный FK откатывает уже вставленный чат. Гонку username решает UNIQUE, а не предварительный SELECT. READ COMMITTED достаточен для нынешних операций: изменения/удаления членства нет. История читается с основной БД без кэша, поэтому подтверждённое сообщение видно следующему подходящему чтению. Cursor хранит (created_at,id) и scope; несколько страниц не составляют общий snapshot. Откат часов может поместить запись до уже пройденной границы.
PostgreSQL: fsync=on, synchronous_commit=on, full_page_writes=on и named volume. COMMIT подтверждает фиксацию в настроенной модели durability, но не отказоустойчивость единственного диска/host.
Пароли, сессии и роль Valkey
Пароли обрабатываются Argon2id, профиль RFC_9106_LOW_MEMORY, с отдельной случайной солью. UTF-8 не усекается: 12–128 code points, двоеточие допустимо. Максимум два одновременных KDF ограничивают расход памяти; при исчерпании бюджета ожидания — 503. Для неизвестного имени проверяется dummy hash. Неверный пароль и неизвестное имя получают одинаковую ошибку 401.
Basic применяется только на POST /api/v1/auth/sessions без body. Выдаётся opaque token из 32 случайных байтов, в БД — только его SHA-256, user_id и абсолютный expires_at по часам БД. Быстрый digest здесь нужен для поиска случайного секрета, а не вместо password KDF. В User нет пароля/hash. Защищённые endpoint принимают Bearer, X-User-Id игнорируется. Каждый 401 имеет нужный WWW-Authenticate; logout — 204 без тела, повтор — 401.
SESSION_TTL_SECONDS по умолчанию 3600. В тесте через переменную окружения задаётся 2 с, затем приложение пересоздаётся с обычным TTL; прежняя сессия всё равно истекает через исходные 2 с. Рестарт не продлевает expiry.
Каждый запрос проверяет наличие/expiry сессии в PostgreSQL. Valkey с TTL позволяет пропустить повторный SELECT неизменяемой User. На miss карточка читается из БД, на hit этот SELECT не нужен. Ключ кэша не подтверждает действительность токена. Logout сначала фиксируется в БД, затем удаляет ключ; даже специально возвращённый stale key не оживляет сессию.
Valkey: 64 MiB, allkeys-lru, persistence выключен, поскольку это не источник истины. Flush/eviction/restart приводят к cache miss; данные и сессии остаются в PostgreSQL. Кэш обходится при отказе, таймауты клиента 0,2 с, retry выключены. При отказе PostgreSQL даже cache hit не даёт доступ. Readiness проверяет критичную БД, liveness — жизнь процесса.
Проверки и доказательства
| Критерий | Наблюдение | Доказательство |
|---|---|---|
| Контракт | make check и validate прошли; исходные tests/contracts не изменены | evidence/contract-checks.txt |
| Публичный сценарий | make test: PASS lab2 | evidence/smoke.txt |
| Persistence | Прежний токен читает прежнее сообщение после полного restart | evidence/persistence.txt |
| Реальные процессы | StartedAt и PID API/PostgreSQL/Valkey изменились | evidence/lifecycle.json |
| Миграции | Применение с нуля, повтор без дублей, отказ при изменённом checksum | student-tests, lifecycle.json |
| UNIQUE и rollback | 10 HTTP-регистраций: один 201 и девять 409; ошибочный чат не оставляет строк | evidence/student-tests.txt |
| Строгий API/ACL | Неверный JSON/тип/Unicode/cursor; чужой чат; Basic вместо Bearer; подмена X-User-Id | student-tests/test_api.py |
| Конкурентные записи | 10 клиентов, 100 сообщений, точное равенство множеств ID | evidence/lifecycle.json |
| Кэш и отзыв | Hit избегает User SELECT; flush восстанавливает ключ; stale key не обходит logout | student-tests/test_api.py |
| Expiry | SESSION_TTL_SECONDS=2; пересоздание приложения не продлевает сессию | evidence/student-tests.txt |
| Отказы | Valkey: 200 действующей сессии, 401 анониму; БД: 503, liveness 200 | evidence/lifecycle.json |
| Индекс и трек 5 | Два индекса, три повтора, 100 000 сообщений; запись и backup/restore | evidence/query-plan.json |
| Non-root и логи | UID 10001; canary, пароли и токены отсутствуют в проверенных API logs | evidence/lifecycle.json |
36 собственных случаев используют настоящие PostgreSQL и Valkey, а не SQLite/mock SQL. TestClient дополнен публичным TCP smoke и реальными контейнерными отказами. Есть предупреждение библиотеки TestClient об устаревающем HTTP-клиенте; проверки выполняются. Ruff прошёл. Пути рабочей машины в доказательствах заменены на <project>; секреты не сохраняются.
При отключённом Valkey корректный ответ получен за 0,254 с. При остановленном PostgreSQL запрос с закэшированной сессией получил 503 за 1,006 с, readiness — за 1,008 с. После восстановления все 100 подтверждённых сообщений остались прежними. Это измерения конкретного запуска, не обещанный SLA.
Исследование: план запроса и восстановление
Гипотеза: индекс только по chat_id вынуждает читать много строк и сортировать историю, а (chat_id,created_at,id) позволяет остановиться после небольшой keyset-страницы. У дополнительного индекса есть цена размера и записи.
Методика: 100 000 сообщений в 10 чатах с размерами 90 000 / 5 000 / 2 000 / 1 000 / 500 / 500 / 250 / 250 / 250 / 250. Перед каждым из шести прогонов история пересоздаётся с теми же ключами/текстом, установлен ровно один сравниваемый вторичный индекс и выполнен VACUUM ANALYZE. Общие PK/FK сохраняются. Порядок: AB, BA, AB.
На прогон: EXPLAIN (ANALYZE, BUFFERS) для большого чата с первой/глубокой страницей и малого чата с глубокой; 20 прогревочных и 200 измеряемых SELECT, конкуренция 1, closed-loop, страница до 51 строки. 75% запросов — большой чат, 25% — малый; чередуются начало и позиция около 90%. Затем 20 транзакций по 100 новых сообщений: время с COMMIT, WAL delta и размер индекса. После записи — 102 000 сообщений.
PostgreSQL: 1 CPU/512 MiB, swap сверх лимита запрещён. API: 1 CPU/512 MiB; Valkey: 0,5 CPU/128 MiB. Генератор SQL на Mac через localhost, Docker VM: 18 vCPU, около 7,75 GiB RAM. Raw durations и CPU/RAM samples сохранены. Вся серия заняла около 24 с с подготовкой/restore. Это короткий SQL-микроэксперимент, не HTTP API latency/RPS.
| Медиана трёх повторов | Только chat_id | chat_id,created_at,id |
|---|---|---|
| SELECT в секунду | 164,77 | 2092,27 |
| p95 SELECT, мс | 8,877 | 0,671 |
| Записанных строк/с, batch=100 | 26 621,51 | 26 986,71 |
| Размер вторичного индекса после записи | 688 128 B | 6 127 616 B |
В одном плане глубокой страницы большого чата до изменения — 2703 shared hit blocks и Sort, после — Index Scan и 5 shared hit blocks. Деревья и Execution Time есть в JSON; seqscan принудительно не отключался.
Стоимость записи измерена, но короткая серия не доказывает её улучшения: диапазоны перекрываются, есть шум клиента/VM и batch COMMIT. Явная цена — вторичный индекс примерно в 8,9 раза больше. Медиана трёх p95 не равна общему p95. CPU/RAM — редкие выборки, для быстрых прогонов недостаточные для оценки пиков. Кэш cluster не сбрасывался; прогрев и чередование уменьшают, но не устраняют дрейф. Производительность локального SQL-клиента также ограничивает результат.
Backup → новая БД → сверка
После последнего прогона создаётся сессия и custom-format pg_dump. Pg_restore восстанавливает архив в новую пустую БД. Совпали количества: 2 пользователя, 10 чатов, 20 членств, 102 000 сообщений, 1 сессия, 1 миграция. Дополнительно совпали восемь выбранных сообщений и SHA-256 полного упорядоченного содержимого всех сообщений.
Архив: 2 723 619 B. Dump — 0,368 с, создание новой БД и restore — 0,510 с. Это время локальной логической операции, не полный RTO сервиса: переключение API, перенос с другого host и production-размеры не измерялись. Raw dump содержит password hashes/сессионные digest и удаляется с временным каталогом; в Git остаются только результаты сверки.
После backup в исходной БД специально подтверждено ещё одно сообщение. В восстановленной БД его нет: snapshot не включает более поздние COMMIT. Для них нужны WAL/PITR или новый backup. Так показана граница потери данных; нулевой RPO не заявляется. Копия на том же host не защищает от его потери. Процедура: research/query_plan.py.
Ограничения и следующие шаги
Один PostgreSQL и host — SPOF; volume не заменяет внешний backup. Valkey можно потерять, PostgreSQL — нет. Нет реплик БД, PITR, TLS и rate limiting по клиенту. Просроченные сессии не дают доступа, но их строки пока сохраняются; уборка — отдельная эксплуатационная задача. Учебная роль БД не является production-моделью минимальных привилегий. Basic/Bearer по HTTP допустимы только на локальном изолированном стенде.
В lab3 отдельно добавляются балансировщик, API-реплики, X-Instance-Id и атомарная идемпотентность отправки. Это не заявляется реализованным в lab2. Secrets, volumes и история .git между работами не переносятся.
Источники
Нормативные: README.md, COURSE.md, CONTRIBUTING.md и contracts/ этой лабораторной. Предыдущая реализация — собственная lab1; публичные tests не изменялись. Используются перечисленные библиотеки из uv.lock.
- Psycopg: connection pools
- PostgreSQL: multicolumn indexes
- PostgreSQL: EXPLAIN
- PostgreSQL: SQL dump
- Argon2-cffi: password hashing API
- Basic authentication, RFC 7617
Соответствие ревизий
После редактуры отчёта, шаблона и служебных метаданных сохранено соответствие прежних и текущих Git-ревизий: revision-map.json. Код приложения, миграции, зависимости, Dockerfile, конфигурация сервисов и исходные публичные проверки не изменены. Численные результаты и исторические image/source identifiers в evidence сохранены в исходном виде; их не следует трактовать как новый запуск измерений.