Files
mtusi2026lab2/REPORT.md
T

20 KiB
Raw Permalink Blame History

Отчёт — лабораторная 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.

Соответствие ревизий

После редактуры отчёта, шаблона и служебных метаданных сохранено соответствие прежних и текущих Git-ревизий: revision-map.json. Код приложения, миграции, зависимости, Dockerfile, конфигурация сервисов и исходные публичные проверки не изменены. Численные результаты и исторические image/source identifiers в evidence сохранены в исходном виде; их не следует трактовать как новый запуск измерений.