forked from mtusi2026/mtusi2026lab2
115 lines
10 KiB
Markdown
115 lines
10 KiB
Markdown
# Отчёт — лабораторная 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 допускается только для локального
|
||
изолированного стенда с синтетическими данными.
|