Files
mtusi2026lab2/REPORT.md

115 lines
10 KiB
Markdown
Raw Permalink 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
- Автор, группа: Яковлев Матвей Дмитриевич, БПИ2304
- Целевая оценка; выбранный трек 5, если нужен: 3
- Commit/PR: ветка: (solution/BPI2304-Yakovlev); MR: (https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2/pulls/189)
- Использованные источники, библиотеки и помощь ИИ: Python 3.12, FastAPI 0.135.3, Uvicorn 0.44.0, psycopg 3.3.3, PostgreSQL 16-alpine, Dockerfile из репозитория; версии закреплены в `requirements.txt`, `compose.yaml` и `Dockerfile`. При подготовке использовалась помощь Claude.
## Запуск из чистого clone
Требуется Docker с Compose. Секреты создаются локально и в Git не попадают (`.env` игнорируется).
```sh
git clone <url-вашего-fork> && cd <каталог>
cp .env.example .env
# В .env задайте синтетические локальные POSTGRES_USER / POSTGRES_PASSWORD /
# POSTGRES_DB / DATABASE_URL. Пример: postgresql://messenger:<password>@db:5432/messenger
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
curl -i http://localhost:8080/health/ready # 200 {"status":"ok"}
python tests/smoke.py --base-url http://localhost:8080
```
Без Docker (для отладки): задайте `DATABASE_URL` на доступный PostgreSQL, создайте БД.
`python -m venv .venv && .venv/bin/pip install -r requirements.txt && .venv/bin/python -m app`.
Миграции применяются при старте приложения; повторный запуск ничего не дублирует
(`schema_migrations` хранит список применённых файлов).
Остановка и безопасная работа с данными:
```sh
docker compose --env-file .env stop api db # данные остаются в volume pgdata
docker compose --env-file .env start api db
# Явное намеренное удаление учебных данных (не используется в тестах):
docker compose --env-file .env down -v
```
Проверка сохранности (перезапуск API **и** PostgreSQL с сохранением volume):
```sh
# Linux/macOS:
make test-persistence ACTION_SCRIPT=scripts/restart.sh
# Windows (локально):
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://localhost:8080
```
Полный вывод команд — `evidence/lifecycle.txt`.
## Архитектура и решения
Клиент → FastAPI/Uvicorn (один процесс, один worker) → PostgreSQL 16.
- **Источник истины** — PostgreSQL. Все обязательные данные (пользователи, чаты,
участники, сообщения, сессии) хранятся в таблицах; процесс не держит их копию.
Приложение использует небольшой пул соединений (`DB_POOL_MAX`, по умолчанию 8)
с таймаутом подключения 3 с.
- `migrations/001_init.sql` — версионируемая схема: PK/FK, `UNIQUE(username)`,
CHECK-ограничения длины/формата, индексы `ix_chat_members_user`,
`ix_messages_history (chat_id, created_at, id)`, `ix_sessions_expiry`.
Применяется один раз, фиксируется в `schema_migrations`.
- **Транзакции**: регистрация пользователя, создание чата (проверка участников + chat
+ все membership-строки) и отправка сообщения выполняются в одной транзакции;
при ошибке — rollback. Уникальность username и включение вызывающего в `member_ids`
проверяются до вставки.
- **Аутентификация lab2**: `POST /auth/sessions` принимает только Basic; пароль
проверяется библиотечным KDF `hashlib.scrypt` (n=2^14, r=8, p=1, соль 16 байт,
256-битный вывод) — не SHA-256 и не plaintext. Сессия — непрозрачный токен
(256 бит entropy, `urlsafe_b64encode(os.urandom(32))`); в БД хранится только
SHA-256 хэш токена, `expires_at` и `user_id`. TTL задаётся `SESSION_TTL_SECONDS`
(по умолчанию 3600). Бизнес-endpoint'ы принимают только `Bearer`; `X-User-Id`
игнорируется. Logout удаляет строку сессии. Basic на бизнес-endpoint и неверный
Bearer получают 401 с корректным `WWW-Authenticate`.
- **Пагинация** — keyset по `(created_at, id)`; курсор — base64url JSON с привязкой
к типу ресурса и ID чата/пользователя, поэтому курсор другого чата даёт 400.
Индекс `ix_messages_history` позволяет читать одну страницу без полного scan истории.
- **Отказы**: `/health/ready` делает `SELECT 1` и возвращает 503 в общем формате
ошибки, если БД недоступна. `X-Request-Id` есть в каждом ответе; `X-Instance-Id`
стабилен для процесса. `POST /users` с занятым username → 409, чужой чат и
несуществующий чат → одинаковый 404.
- Соответствие `.env.example`: переменные `DATABASE_URL` / `DATABASE_URL_FILE`
и `SESSION_TTL_SECONDS`; `SESSION_STORE=postgres` — level 3, Redis/Valkey не
используется (уровень 4 не заявляется).
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | `python tests/smoke.py --base-url http://localhost:8080` | `PASS: lab2 public API scenario...` | `evidence/lifecycle.txt`, раздел 4 |
| Данные и сессии переживают рестарт API+БД | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` (на Windows — `scripts/restart.cmd`) | `PASS: persistence preserved confirmed data and existing session`; старый Bearer-токен читает те же данные; счётчики строк до/после рестарта, `schema_migrations` без повторов | `evidence/lifecycle.txt`, разделы 3, 6, 7 |
| PostgreSQL, FK/PK/UNIQUE, миграции с нуля | `docker compose up -d --build`; `psql ... SELECT` | две таблицы миграций/данных созданы с чистого volume; `001_init.sql` применён один раз | `evidence/lifecycle.txt`, разделы 1, 3 |
| Basic только на /auth/sessions, Bearer на остальных, expiry и logout | публичный smoke: 401 на Basic для `/users/me`, 401 на `X-User-Id`, проверка `X-User-Id` поверх Bearer, logout → 401 | PASS | `evidence/lifecycle.txt`, раздел 4 |
| Пароли хешируются password KDF | `python -m unittest discover -s student-tests` | 9 тестов OK: scrypt, соли, UTF-8 пароль с `:` | `evidence/lifecycle.txt`, раздел 8 |
| Атомарное создание чата, rollback и курсор | smoke + собственные юнит-тесты | PASS; курсор привязан к чату, мусор отклоняется | `evidence/lifecycle.txt`, разделы 4, 8 |
## Эксперименты и отказы
Не проводились (целевая оценка 3). Для уровня 5 потребовались бы отдельные
исследования согласованности кэша или плана запросов — в этой работе не заявлены.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| Перезапуск API и PostgreSQL с сохранением `pgdata` | пользователи, чаты, сообщения и действующая сессия остаются; токен работает | подтверждённые данные и тот же Bearer-токен прочитаны после рестарта; `schema_migrations` без повторов | автоматический hook + ожидание готовности; потеря данных — 0 |
## Ограничения и следующие шаги
- Уровень 4 не реализован: Redis/Valkey не подключается (`SESSION_STORE=postgres`),
нет отдельного теста expiry при коротком TTL и автоматической проверки отказа БД —
эти пункты требует оценка 4.
- Один процесс API: `created_at` назначается сервером, порядок страниц определяется
`(created_at, id)`; при параллельной вставке возможны одинаковые метки времени,
но детерминированный second key (`id`) исключает потери/дубли при обходе неизменной истории.
- Хранение сессий в PostgreSQL означает, что рестарт БД сохраняет сессии только
вместе с volume `pgdata`; `down -v` удаляет их намеренно.
- Для удалённой демонстрации нужен TLS: HTTP допускается только для локального
изолированного стенда с синтетическими данными.