10 KiB
Отчёт — лабораторная 2
- Автор, группа: Яковлев Матвей Дмитриевич, БПИ2304
- Целевая оценка; выбранный трек 5, если нужен: 3
- Commit/PR: ветка: (solution/BPI2304-Yakovlev); MR: (mtusi2026/mtusi2026lab2#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 игнорируется).
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 хранит список применённых файлов).
Остановка и безопасная работа с данными:
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):
# 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проверяются до вставки.
- все membership-строки) и отправка сообщения выполняются в одной транзакции;
при ошибке — rollback. Уникальность username и включение вызывающего в
- Аутентификация lab2:
POST /auth/sessionsпринимает только Basic; пароль проверяется библиотечным KDFhashlib.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 допускается только для локального изолированного стенда с синтетическими данными.