8.9 KiB
8.9 KiB
Отчёт — лабораторная 2
- Автор, группа: Мякишев Владислав, БПИ2302
- Целевая оценка: 3
- Commit/PR: TODO после публикации
- Источники и библиотеки: FastAPI, SQLAlchemy 2.1 (ORM), Alembic, psycopg 3, argon2-cffi, PyJWT; документация PostgreSQL, Alembic, RFC 7617. При разработке использовался ИИ-ассистент (Claude).
Запуск из чистого clone
Нужно: Docker с Compose v2, Python 3.9+ (для тестов). Образы: postgres:17.10-alpine, python:3.14.3-slim (закреплены digest в compose.yaml/Dockerfile).
sh scripts/init-secrets.sh # Windows: powershell -File scripts\init-secrets.ps1
docker compose up -d --build --wait # postgres (healthy) -> migrate (exit 0) -> api (healthy)
make test # публичный smoke
chmod +x scripts/restart.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
init-secretsсоздаётsecrets/postgres_password,secrets/jwt_secret(случайные, не выводятся, вне Git) и.envиз.env.example.- Миграции применяет разовый сервис
migrate(alembic upgrade head) при каждомup; повторный запуск ничего не меняет. - Остановка без потери данных:
docker compose down. Намеренное удаление учебных данных:docker compose down -v. - Свои тесты (нужен запущенный
postgres, используют отдельную базуmessenger_test):python -m venv .venv && .venv/bin/pip install -r requirements-test.txt && .venv/bin/python -m pytest - На Windows тест сохранности:
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd(restart.cmd— те же команды, чтоrestart.sh).
Архитектура и решения
Клиент → API (FastAPI, api) → PostgreSQL 17 (postgres, volume postgres_data). PostgreSQL — источник истины для пользователей, чатов, участников, сообщений и сессий (SESSION_STORE=postgres).
| Роль | Сервис | Готовность | Хранилище | Порт | Credentials |
|---|---|---|---|---|---|
| база | postgres |
pg_isready |
volume postgres_data |
127.0.0.1:5432 | secret postgres_password |
| миграции | migrate |
exit 0 | — | — | secret postgres_password |
| API | api |
/health/live (Docker), /health/ready (проверяет БД) |
нет | 127.0.0.1:8080 | secrets postgres_password, jwt_secret |
- Схема (миграция
0001):users(UNIQUE username, CHECK формата),sessions(PK = SHA-256 токена,expires_at),chats,chat_members(PK(chat_id, user_id)),messages(составной FK(chat_id, sender_id)→chat_members, индекс(chat_id, created_at, id)для keyset-пагинации). - Транзакции: создание чата — одна транзакция (чат + все участники); 201 возвращается только после COMMIT. Дубль username отсекается ограничением
users_username_key→ 409. - Аутентификация: регистрация с паролем (Argon2id).
POST /auth/sessionsпринимает только Basic и выдаёт JWT (HS256,sub/iat/exp/jti,jti— 256 бит случайности). На сервере хранится сессия (хеш токена + срок). Bearer проверяется по подписи,expи наличию сессии в БД; logout удаляет сессию.X-User-Idне читается. - Из lab1 перенесено: весь API, формат ошибок,
X-Request-Id, cursor-пагинация, Dockerfile. Изменено: хранилище в памяти → PostgreSQL (app/models,app/database_functions), X-User-Id → Basic/Bearer, добавлены Compose и миграции. - Переменные (
.env.exampleкурса → наши):APP_HOST/APP_PORT→APP_CONFIG__RUN__HOST/PORT;DATABASE_URL_FILE→APP_CONFIG__DB__HOST/PORT/NAME/USER+APP_CONFIG__DB__PASSWORD_FILE;SESSION_TTL_SECONDS→APP_CONFIG__JWT__SESSION_TTL_SECONDS(3600).
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Публичный smoke | make test против стенда в Compose |
PASS: lab2 public API scenario |
вывод команды |
| Данные и действующие сессии переживают рестарт API и БД без удаления volumes | make test-persistence ACTION_SCRIPT=scripts/restart.sh (на Windows — restart.cmd) |
PASS: persistence preserved confirmed data and existing session; у api и postgres новый StartedAt при тех же id контейнеров и том же volume |
evidence/persistence.txt |
| Таблицы, PK/FK, UNIQUE username, миграции с нуля | alembic downgrade base → alembic upgrade head; alembic check |
схема создаётся заново; No new upgrade operations detected |
app/migrations/versions/0001_initial_schema.py |
| Повторные миграции без дублей | docker compose up при существующей схеме |
migrate завершается с кодом 0 без Running upgrade, данные не меняются |
docker compose logs migrate |
| Атомарное создание чата | pytest student-tests/test_chats_api.py |
при неизвестном участнике — 400 и 0 строк в chats/chat_members |
student-tests/test_chats_api.py |
| Basic только на входе, Bearer, expiry, logout, X-User-Id не работает | pytest student-tests/test_auth_api.py + smoke |
401 с корректным WWW-Authenticate; токен после logout и после TTL → 401 |
student-tests/test_auth_api.py |
| Пароли — password KDF | pytest student-tests/test_users_api.py |
в БД $argon2id$…, в ответах пароля нет |
student-tests/test_users_api.py |
| Секреты/volumes вне Git | git status --ignored |
.env, secrets/ в игноре |
.gitignore |
| Свои тесты | python -m pytest |
30 passed |
student-tests/ |
Проверка истечения на стенде: APP_CONFIG__JWT__SESSION_TTL_SECONDS=2 docker compose up -d --wait api → войти, подождать 3 с → запрос с токеном даёт 401. Вернуть: docker compose up -d --wait api.
Эксперименты и отказы
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
scripts/restart.sh: stop + up API и PostgreSQL |
данные и сессии сохраняются | test-persistence PASS, тот же токен работает | ~22 с на весь сценарий; потерь нет |
docker compose stop postgres при работающем API |
/health/ready → 503, бизнес-запросы → 503 без деталей |
503 через ~3 с (connect_timeout); после start — 200 без рестарта API (pool_pre_ping) |
несколько секунд; потерь нет |
SIGTERM API (docker compose stop api) |
корректное завершение | Shutting down → Соединения с базой данных закрыты → Finished server process |
— |
Ограничения и следующие шаги
- Один экземпляр API и одна PostgreSQL без реплик и бэкапов: потеря volume = потеря данных.
- Токен — JWT: payload (UUID пользователя, время) читается клиентом, секретов в нём нет; отзыв обеспечивается серверной сессией.
- При одновременной записи курсор может пропустить сообщение, чьё
created_atменьше уже выданного (окно — время между INSERT и COMMIT); повторное чтение с начала его показывает. Время назначает PostgreSQL. - Истёкшие сессии из таблицы не удаляются автоматически (индекс по
expires_atесть). - Не сделано (уровень 4): Redis/Valkey, EXPLAIN на ≥10 000 сообщений, тест гонки регистрации.