Files
mtusi2026lab2/REPORT.md
T

133 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 2
Автор: **Горбанюк, БВТ2301**. Целевая оценка: **5**, трек 2 «План запроса и восстановление». Подготовлено локально 17.10.2026; форк и МР этой работы пока не создавались.
## Запуск из чистого 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 и транзитивные зависимости.
```sh
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. БД и кэш по умолчанию не публикуют порты хоста. Для интеграционных проверок:
```sh
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.
```sh
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](SCHEMA.md). [Миграция](migrations/001_initial.sql) задаёт 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](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](https://www.psycopg.org/psycopg3/docs/advanced/pool.html)
- [PostgreSQL: multicolumn indexes](https://www.postgresql.org/docs/18/indexes-multicolumn.html)
- [PostgreSQL: EXPLAIN](https://www.postgresql.org/docs/18/using-explain.html)
- [PostgreSQL: SQL dump](https://www.postgresql.org/docs/18/backup-dump.html)
- [Argon2-cffi: password hashing API](https://argon2-cffi.readthedocs.io/en/stable/api.html)
- [Basic authentication, RFC 7617](https://www.rfc-editor.org/rfc/rfc7617)