Files
mtusi2026lab2-fork/REPORT.md
T
2026-11-17 00:04:04 +03:00

141 lines
8.8 KiB
Markdown
Raw 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
- Автор, группа: Гадяцкий Л. Е., БПИ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 допустим только на локальном учебном стенде с синтетическими данными.