forked from mtusi2026/mtusi2026lab2
141 lines
8.8 KiB
Markdown
141 lines
8.8 KiB
Markdown
# Отчёт — лабораторная 2
|
||
|
||
- Автор, группа: Гадяцкий Л. Е., БПИ2302
|
||
- Целевая оценка: 3
|
||
- Commit/PR:`solution/BPI2302-Gadiatskiy` MR#167: https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2/pulls/167
|
||
- Использованные источники и библиотеки:
|
||
- контракт и семантика: `contracts/openapi.json`, `contracts/README.md`, `README.md`, `COURSE.md`
|
||
- перенос из lab1: FastAPI, cursor-пагинация, формат ошибок, стиль Dockerfile
|
||
- runtime: FastAPI 0.115.6, Uvicorn 0.34.0, Pydantic 2.10.4, SQLAlchemy 2.0.36, psycopg 3.2.4, argon2-cffi 23.1.0
|
||
- PostgreSQL: образ `postgres:16-alpine`
|
||
- Помощь ИИ использована при переносе lab1, реализации PostgreSQL/сессий/SQLAlchemy и отчёта. Результаты подтверждаются сохранёнными запусками.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
**Prerequisites:** Docker и Docker Compose. Python 3.9+ нужен только для публичных проверок (`make check` / `make test` / `tests/resilience.py`). Runtime приложения — внутри образа.
|
||
|
||
**Версии:**
|
||
- API: базовый образ `python:3.12.8-slim-bookworm` → локальный `mtusi-messenger:lab2`
|
||
- PostgreSQL: `postgres:16-alpine`
|
||
- зависимости: `requirements.txt`
|
||
|
||
**Конфигурация:** секретов в Git нет. Локальный `.env` создаётся из примера и не коммитится:
|
||
|
||
```sh
|
||
cp .env.example .env
|
||
```
|
||
|
||
Соответствие `.env.example`:
|
||
- `APP_HOST` / `APP_PORT` — bind uvicorn внутри контейнера
|
||
- `HOST_PORT` — порт на host (по умолчанию 8080; если занят — например 8081)
|
||
- `APP_ENV` — среда запуска (`lab`)
|
||
- `SESSION_TTL_SECONDS` — TTL сессии (по умолчанию 3600; для обычного smoke ≥ 300)
|
||
- `SESSION_STORE=postgres` — сессии в PostgreSQL
|
||
- `DATABASE_URL` — строка подключения API к PostgreSQL в compose-сети
|
||
(приложение также поддерживает `DATABASE_URL_FILE`)
|
||
|
||
Учебные credentials compose (`messenger` / `messenger`) только для локального синтетического стенда.
|
||
|
||
**Сборка и запуск:**
|
||
|
||
```sh
|
||
docker compose --env-file .env up -d --build
|
||
```
|
||
|
||
Готовность (подставьте свой `HOST_PORT`):
|
||
|
||
```sh
|
||
curl -i http://127.0.0.1:8080/health/ready
|
||
```
|
||
|
||
Ожидается HTTP 200, тело `{"status":"ok"}`, заголовок `X-Request-Id`.
|
||
Миграции `migrations/*.sql` применяются при старте API идемпотентно через таблицу `schema_migrations`.
|
||
|
||
**Публичный smoke** (при уже запущенном стенде):
|
||
|
||
```sh
|
||
python tests/smoke.py --base-url http://127.0.0.1:8080
|
||
# или: make test BASE_URL=http://127.0.0.1:8080
|
||
```
|
||
|
||
**Проверка сохранности:**
|
||
|
||
```sh
|
||
# Unix:
|
||
chmod +x scripts/restart.sh
|
||
python tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080
|
||
|
||
# Windows:
|
||
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8080
|
||
```
|
||
|
||
Hook выполняет `docker compose --env-file .env restart` для API и PostgreSQL **без** удаления volumes (`down -v` не используется).
|
||
|
||
Локальная проверка автора выполнялась на `HOST_PORT=8081` (host-порт 8080 был занят другим контейнером).
|
||
|
||
**Остановка:**
|
||
|
||
```sh
|
||
docker compose --env-file .env down
|
||
```
|
||
|
||
Намеренное удаление учебных данных (volumes):
|
||
|
||
```sh
|
||
docker compose --env-file .env down -v
|
||
```
|
||
|
||
## Архитектура и решения
|
||
|
||
```
|
||
HTTP-клиент
|
||
→ api (uvicorn + FastAPI)
|
||
→ SQLAlchemy ORM
|
||
→ PostgreSQL
|
||
users, chats, chat_members, messages, sessions
|
||
```
|
||
|
||
- Источник истины — PostgreSQL. In-memory store lab1 заменён.
|
||
- ORM-модели: `src/messenger/tables.py`. Доступ к данным: `src/messenger/store.py`.
|
||
- Схема версионируется SQL-файлами в `migrations/`; runner — `apply_migrations()` в `src/messenger/db.py` (учёт в `schema_migrations`). Alembic не используется.
|
||
- Регистрация требует `password`; hash — Argon2id (`argon2-cffi`). В ответе User пароль/hash не возвращаются.
|
||
- `POST /auth/sessions` — только Basic; opaque Bearer-токен (`secrets.token_urlsafe(32)`, ≥256 бит энтропии). В БД хранится SHA-256 токена, `expires_at`, `revoked_at`.
|
||
- Защищённые endpoint принимают только Bearer. `X-User-Id` игнорируется и сам по себе доступа не даёт. Basic на бизнес-endpoint → 401.
|
||
- Создание чата (chat + members) — одна транзакция SQLAlchemy.
|
||
- Keyset-пагинация и формат ошибок перенесены из lab1.
|
||
- `/health/live` — процесс; `/health/ready` — доступность PostgreSQL (иначе 503).
|
||
- Compose: сервисы `api` + `postgres`, volume `pgdata`, secrets/`.env` в Git не коммитятся.
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||
| --- | --- | --- | --- |
|
||
| Минимум lab1 + переход на auth; публичный smoke | `python tests/smoke.py --base-url http://127.0.0.1:8081` | `PASS: lab2 public API scenario...` | `evidence/smoke.txt` |
|
||
| Данные и действующие сессии переживают рестарт без удаления volumes | `python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://127.0.0.1:8081` | `PASS: persistence preserved confirmed data and existing session...` | `evidence/restart.txt` |
|
||
| PostgreSQL: users/chats/members/messages; PK/FK; unique username; миграции с нуля; атомарный чат | `migrations/001_init.sql` + `store.create_chat` в транзакции; повторный restart API | в `schema_migrations` одна запись `001_init.sql`; число users не размножается при повторном migrate | код + проверка ниже |
|
||
| Basic только на login; Bearer; TTL/logout; X-User-Id не даёт доступ; password KDF | сценарии внутри smoke (wrong password, Basic на `/users/me`, `X-User-Id`, logout) | соответствующие 401 / logout → 401 | `evidence/smoke.txt` |
|
||
| Повторный запуск миграций без дублирования данных; secrets/volumes не в Git | restart API после persistence; `.gitignore` для `.env` и `volumes/` | `001_init.sql` применена один раз; users сохраняются | этот отчёт |
|
||
|
||
Повторная проверка идемпотентности миграций после persistence:
|
||
|
||
```text
|
||
SELECT version FROM schema_migrations; → 001_init.sql (1 row)
|
||
SELECT COUNT(*) FROM users; → данные на месте, без дублирования схемы
|
||
```
|
||
|
||
## Эксперименты и отказы
|
||
|
||
Для оценки 3 отдельный нагрузочный трек не выполнялся. Проверена сохранность:
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| `docker compose --env-file .env restart` (API + PostgreSQL), volumes сохранены | `/health/ready` ok; прежний Bearer читает те же users/chats/messages; сессия действует | persistence PASS | в бюджете теста (hook ≤90 с, ready ≤90 с); потери данных нет |
|
||
|
||
Аппаратный профиль: локальный Docker Desktop на Windows; один API и один PostgreSQL без CPU/RAM limits.
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
- Redis/Valkey, EXPLAIN на ≥10k сообщений, отдельные автотесты expiry/гонки/недоступности зависимостей не выполнялись.
|
||
- Сессии и бизнес-данные в одном PostgreSQL; недоступность БД → `/health/ready` = 503.
|
||
- Basic по HTTP допустим только на локальном учебном стенде с синтетическими данными.
|