Files
mtusi2026lab2/REPORT.md
T

167 lines
14 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**.
Публикация пока не выполнялась: аккаунт и собственный fork будут предоставлены позднее.
Ветка: `solution/bvt2301-vasilev`. Автор коммитов: `n.a.vasilev@edu.mtuci.ru`.
Исходные README, COURSE, CONTRIBUTING, contracts и публичные tests сохранены.
Помощь ИИ использована при разборе требований, подготовке реализации, тестов и
материалов защиты. Все заявленные результаты подтверждаются реальными запусками;
чужие реализации, история и результаты измерений не использованы как собственные.
Выбран трек2: **план запроса и восстановление**.
Исходный проект: [задание преподавателя](https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2)
Название будущего МР: **ЛР 2 — БВТ2301 — Васильев — на 5**.
## Запуск из чистого clone
Нужны Docker с Compose, Git, uv и Python3.12. Все зависимости закреплены uv.lock.
Runtime Python3.12.13, FastAPI0.162.0, Pydantic2.14.2, Uvicorn0.54.0;
PostgreSQL17.10-alpine и Valkey8.1.3-alpine. Dockerfile использует digest Python.
```sh
uv sync --locked --python 3.12
make up
make check validate PYTHON=.venv/bin/python
make lint test-student
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
```
`make up` вызывает bootstrap, собирает образ с OCI revision, поднимает PostgreSQL
и Valkey, выполняет миграции отдельным сервисом, ждёт healthy API.
API: http://127.0.0.1:8082. Обычный Compose не публикует порты PostgreSQL/Valkey.
Полная проверка короткого TTL и реальных отказов:
```sh
VCS_REF=$(git rev-parse HEAD) docker compose -f compose.yaml -f compose.test.yaml up -d --build --wait
python3 scripts/verify_lifecycle.py --output evidence/lifecycle-repeat.json
python3 scripts/verify_pool.py --output evidence/pool-repeat.json
uv run --locked python research/run.py --output evidence/query-study-repeat.json
uv run --locked python research/analyze.py evidence/query-study-repeat.json
```
Test override добавляет только отдельную API на127.0.0.1:18082 с TTL 2 s. Обычный
TTL 3600 s, для public persistence не меньше300s. Эксперименты отказов запускать
последовательно. Каждому повтору нужен новый evidence-файл.
Остановка с сохранением данных: `docker compose -f compose.yaml -f compose.test.yaml down`.
Намеренное удаление **только данных этой учебной ЛР2**: та же команда с `--volumes`;
она необратимо удаляет пользователей, сообщения и сессии. Обычная остановка volumes
не удаляет. Не используйте глобальную очистку Docker.
### Настройки и секреты
`scripts/bootstrap.py` создаёт secrets один раз и сохраняет существующие значения.
`.env.example` исходный, переменные сопоставлены так: `APP_HOST/APP_PORT` читаются
сервером; `APP_ENV` зарезервирован; `SESSION_TTL_SECONDS` — срок сессии;
`DATABASE_URL_FILE` и `CACHE_URL_FILE` — файлы URL подключений; `SESSION_STORE`
в этой реализации фиксирован PostgreSQL. Созданный `.env` содержит только PUBLIC_PORT
и TTL. Для другого порта задайте PUBLIC_PORT в окружении и make test PUBLIC_PORT=...
Secrets каталог имеет host mode0700. Файлы0644 внутри него нужны для переносимых
file-backed Compose secret mounts non-root API; в API смонтированы только DB/cache URL,
в PostgreSQL только password. Ни значения, ни `.env`, ни volumes не входят в Git,
образ и сдаваемый пакет. При сохранённых volumes нельзя генерировать новый пароль
вместо старого. Valkey не требует пароля в изолированной внутренней сети; пользователь
с доступом к Docker-host считается доверенным. Для удалённого стенда это требует
дополнительного hardening и TLS.
## Архитектура, схема, транзакции
Клиент → один API → PostgreSQL; Valkey содержит disposable User-карточки с TTL 60 s.
Из собственной ЛР1 перенесены маршруты, строгие схемы, ошибки, ACL, cursor и тесты.
In-memory adapter заменён на `src/messenger/postgres.py`; добавлены password и сессии.
Оригинальные contracts/tests ЛР2 сохранены. Проект не зависит от соседней lab1.
Схема и границы были описаны до SQL: [SCHEMA.md](SCHEMA.md).
Миграция: [001_initial.sql](migrations/001_initial.sql). PK/FK/UNIQUE защищают
users/chats/members/messages/sessions. Составной FK сообщения требует реального
участника чата. Порядок member_ids сохраняется через position. Создание чата и
всех membership — одна транзакция; неизвестный участник откатывает всё.
Миграции выполняются под advisory lock, сохраняют checksum и при изменении
применённого файла завершаются ошибкой. Повторный запуск идемпотентен.
Все значения SQL параметризованы. Пул1..8 соединений, очередь≤32, ожидание2s,
connect2s, statement2.5s, lock1.5s; исчерпание и недоступность дают503.
История использует `(chat_id,created_at,id)` и keyset, без OFFSET.
Чтения autocommit, составные записи в явной транзакции.
Пароли12..128 Unicode code points, без усечения, Argon2id time_cost=2,
memory_cost=65536 KiB, parallelism=1, максимум2 KDF одновременно. Basic разбирается
как UTF-8 по первому двоеточию, только при создании сессии; тело входа игнорируется.
Opaque token —32 случайных байта; PostgreSQL хранит SHA-256 token и абсолютный expiry.
Каждый защищённый запрос сначала читает сессию из PostgreSQL, затем карточку из
Valkey или PostgreSQL. Logout удаляет сессию из источника истины. Кэш не может
воскресить её после logout/expiry и не разрешает авторизацию при отказе PostgreSQL.
Карточки User неизменяемы в обязательном API; поэтому не требуется инвалидация,
TTL/eviction/flush/restart безопасны. История не кэшируется и не бывает stale.
## Доказательства критериев
| Критерий README | Реализация / команда | Наблюдение / evidence |
|---|---|---|
| Сохранённый API с новой идентификацией | make test | [smoke-final.txt](evidence/smoke-final.txt) |
| PG users/chats/members/messages, FK/UNIQUE, атомарность | migrations; test_chat_validation_and_atomicity | [tests-final.txt](evidence/tests-final.txt), [lifecycle.json](evidence/lifecycle.json) |
| Basic/Bearer, password KDF, TTL/logout, X-User-Id игнорируется | test_sessions.py; verify_lifecycle.py | [tests-final.txt](evidence/tests-final.txt), [lifecycle.json](evidence/lifecycle.json) |
| Перезапуск API+PG+cache с тем же токеном | public persistence и actual CID/PID/StartedAt | [lifecycle.json](evidence/lifecycle.json) |
| Повтор миграций, secrets вне Git | verify_lifecycle.py; bootstrap; audit | [lifecycle.json](evidence/lifecycle.json), [audit.json](evidence/audit.json) |
| Valkey реально кэширует, TTL/flush/failure | DBSIZE→flush→repopulate, stop cache | [lifecycle.json](evidence/lifecycle.json) |
| SQL/pool/timeouts, гонка username, rollback | собственные HTTP-тесты; verify_pool.py | [tests-final.txt](evidence/tests-final.txt), [pool.json](evidence/pool.json) |
| Индекс и EXPLAIN≥10000 | реальный dataset100000 | [query-study-final.json](evidence/query-study-final.json) |
| Автоматические expiry/logout/wrong password/отказы | короткий TTL 2 s, рестарт short API, stopPG/cache | [lifecycle.json](evidence/lifecycle.json) |
| Трек5:100k/skew/2индекса/запись/backup/restore | research/run.py | [Методика](research/README.md), [raw](evidence/query-study-final.json), [график](evidence/query-study-final.svg) |
| Чистый независимый clone | новый project/secrets/volume | [clean-clone.json](evidence/clean-clone.json) |
| Структура, OpenAPI, lint | make check validate lint | [contract-final.txt](evidence/contract-final.txt) |
## Исследование и отказы
100000 сообщений, размеры чатов80000/15000/8×625. Сравниваются индекс chat_id
и индекс(chat_id,created_at,id), одинаковый запрос глубокой страницы,5 прогревов,
3фазы на индекс и7 EXPLAIN на фазу. Измерены insertion5000+COMMIT, размер и WAL.
Порядок A/B, B/A, A/B уменьшает дрейф. Все EXPLAIN ANALYZE BUFFERS сохранены.
Числа приведены в [итоге исследования](evidence/query-study-final-summary.md).
Реальный pg_dump-Fc восстановлен в новую БД; совпали counts всех5таблиц,
20полных сообщений и checksum всех100000. Исследовательские БД удаляются finally;
рабочая messenger не очищается. При реальном stopPG старый token получает503,
после восстановления снова действует. При stopcache корректный fallback сохраняет
доступ, а анонимный запрос остаётся401. Повторный logout/expiry —401.
SQL latency не равна HTTP latency. WAL общий для кластера; короткие3серии записи
не доказывают небольшое ускорение/замедление. Прогретый локальный restore не включает
доставку копии или замену hardware. Backup отражает снимок; изменения после него
потеряются без PITR. Одна БД, одинhost и отсутствие TLS остаются ограничениями.
Список чатов содержит дополнительные SQL-запросы для member_ids (N+1 до100чатов);
это ограничивает масштабирование, но не корректность. Старые истёкшие сессии могут
оставаться в таблице до операторской уборки, хотя авторизоваться ими нельзя.
## Ответы на вопросы защиты
1. **COMMIT:** транзакция становится видимой целиком. fsync=on,
synchronous_commit=on и full_page_writes=on обеспечивают запись WAL по настройкам
PostgreSQL; volume сохраняет данные при рестарте, но не при потере единственного диска.
2. **Сессии:** digest и expiry находятся в PostgreSQL. Flush/restart Valkey теряет
только кэш публичных карточек; срок сессии не продлевается и logout не отменяется.
3. **Аутентификация/ACL:** Bearer определяет пользователя, membership разрешает
конкретный чат. Даже действующий token постороннего получает404.
4. **Пароль/checksum:** пароль низкоэнтропийный, нужен дорогой salted KDF;
случайный256-битный token имеет другую модель, SHA-256 используется для его поиска
без хранения оригинального секрета. SHA не подходит вместо Argon2id для паролей.
Подробный конспект: [DEFENSE.md](DEFENSE.md).
Источники: исходный контракт, [PostgreSQL](https://www.postgresql.org/docs/17/),
[psycopg](https://www.psycopg.org/psycopg3/docs/),
[Argon2](https://argon2-cffi.readthedocs.io/), [Valkey](https://valkey.io/topics/).
## Проверенная версия и итог
Независимый чистый clone проверен на `35764f730c90f9797925313875be0a484c13dcff`.
Хеши runtime-модулей в контейнере совпали с исходниками. После этой проверки
runtime-код не изменялся; финальные коммиты добавляют только отчёт и evidence.
Локальные проверки выполнены, публикации и удалённого CI пока не было.
Собственные HTTP-тесты: **61 passed**, без пропусков.
Публичный smoke, структура, OpenAPI, lint и существенные отказы прошли.