Files
mtusi2026lab2/REPORT.md
T

266 lines
24 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
- Автор, группа: Васюкова Наталья, БВТ2303
- Целевая оценка: 4
- Commit/PR: solution/BVT2303-Vasyukova
- Использованные источники, библиотеки и помощь ИИ:
- Контракт: contracts/openapi.json, contracts/README.md
- Инструкции: README.md, COURSE.md, CONTRIBUTING.md
- Библиотеки: fastapi==0.115.0, uvicorn[standard]==0.32.0, psycopg[binary]==3.2.3, psycopg_pool==3.2.3, redis==5.2.0, pydantic (из fastapi)
- ИИ: DeepSeek — помощь в структурировании кода и отчёта. Весь код проверен, отредактирован и запущен разработчиком.
## Запуск из чистого clone
Версии runtime/образов:
- Python: 3.12 (образ `python:3.12-slim`)
- FastAPI 0.115.0, uvicorn[standard] 0.32.0, psycopg[binary] 3.2.3, psycopg_pool 3.2.3, redis 5.2.0
- PostgreSQL 18.6 (на хосте), Redis 7.4.1-alpine (в Compose)
- Docker Desktop (Windows)
### Подготовка PostgreSQL
1. Установить PostgreSQL 18.6, открыть pgAdmin, подключиться к серверу `localhost:5432` под пользователем `postgres`.
2. Создать БД `high_load_messenger`, owner `postgres`.
3. В Query Tool создать роль приложения:
```sql
CREATE ROLE messenger WITH LOGIN PASSWORD 'messenger';
GRANT ALL PRIVILEGES ON DATABASE high_load_messenger TO messenger;
GRANT ALL ON SCHEMA public TO messenger;
```
4. Разрешить подключения из docker-сети: в `postgresql.conf` — `listen_addresses = '*'`, в `pg_hba.conf` — строка для `172.16.0.0/12`/`host.docker.internal`. Перезапустить службу PostgreSQL.
5. Схему таблиц автоматически создаёт приложение на старте (`init_schema()`).
### Запуск стека
1. Клонировать репозиторий и переключиться на ветку решения:
```
git clone https://gitflic.ru/project/vasyukova-nat/mtusi2026lab2.git && cd mtusi2026lab2
git checkout solution/BVT2303-Vasyukova
```
2. Создать `.env` из шаблона и при необходимости поправить `DATABASE_URL`:
```
copy .env.example .env
```
3. Собрать и поднять:
```
docker compose --env-file .env up -d --build
```
4. Проверить готовность:
```
curl.exe -s http://localhost:8080/health/ready
```
Ожидается: `{"status":"ok"}`.
Альтернативный локальный запуск без Docker:
python -m uvicorn src.app.main:app --host 0.0.0.0 --port 8080 --reload
(в `.env` при этом `DATABASE_URL=postgresql://user:password@localhost:5432/high_load_messenger`)
### Проверки
`make` в среде автора недоступен (Windows без GNU Make), поэтому использованы эквивалентные прямые вызовы скриптов. Для Linux/CI рядом указаны команды `make`.
| Makefile-команда | Прямой вызов |
| --- | --- |
| `make check` | `python scripts/check_contract.py` |
| `make validate` | `python scripts/validate_openapi.py` |
| `make test` | `python tests/smoke.py --base-url http://localhost:8080` |
| `make test-student` | `python student-tests/run_all.py --base-url http://localhost:8080` |
| `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `python tests/resilience.py --mode persistence --action-script scripts/restart.bat --base-url http://localhost:8080` |
Примечание про 2 action-скрипта:
`scripts/restart.sh` — обязательный артефакт для Linux/CI; `scripts/restart.bat` — Windows-эквивалент (`tests/resilience.py` запускает action-script напрямую через `subprocess.Popen` не исполняет `.sh` на Windows).
### Остановка и удаление учебных данных
docker compose stop # данные Redis и PostgreSQL (источник истины) сохраняются
docker compose down # volumes Redis сохраняются
docker compose down -v # ТОЛЬКО если осознанно стираем данные Redis
```
## Архитектура и решения
Схема процессов и хранилищ:
```
HTTP-клиент → FastAPI (uvicorn, 0.0.0.0:8080) → PostgreSQL 18.6 (host.docker.internal:5432)
↘ Redis 7.4.1 (redis:6379, AOF everysec)
```
Источник истины:
- PostgreSQL — пользователи, чаты, членство, сообщения.
- Redis — серверные сессии (TTL, инвалидация через logout).
Роль Redis на уровне 4:
- Хранилище серверных сессий с TTL (`SETEX sess:<token> SESSION_TTL_SECONDS ...`).
- Persistence: AOF `appendonly yes`, `appendfsync everysec`, RDB `save 60 1` — сессии переживают рестарт Redis.
- Политика expiry: TTL задаёт сам Redis, продления нет. Инвалидация: `DEL sess:<token>` при `DELETE /auth/sessions/current`.
- Источник истины для сессий — Redis. Если Redis недоступен, `/health/ready` → 503, бизнес-запросы не обслуживаются молча как анонимные.
Схема БД (подробнее - `src/app/storage/db.py`, константа `SCHEMA_SQL`):
```
users(id UUID PK, username TEXT UNIQUE, display_name TEXT, password_hash TEXT, created_at TIMESTAMPTZ)
chats(id UUID PK, title TEXT, created_at TIMESTAMPTZ)
chat_members(chat_id FK→chats, user_id FK→users, PK(chat_id,user_id))
messages(id UUID PK, chat_id FK→chats, sender_id FK→users, text TEXT, created_at TIMESTAMPTZ)
+ INDEX idx_messages_chat_created(chat_id, created_at, id)
sessions(token TEXT PK, user_id FK→users, expires_at TIMESTAMPTZ) -- fallback SESSION_STORE=postgres
```
Применяется идемпотентно через `init_schema()` на старте. Все временные метки — `TIMESTAMPTZ`.
Транзакционные границы:
- `create_user` — SELECT-проверка username и INSERT в одной транзакции; при гонке `UniqueViolation` ловится и превращается в 409.
- `create_chat` — INSERT `chats` + INSERT `chat_members` в одной транзакции, откат целиком.
- `add_message` — один INSERT, отдельная транзакция.
- Создание/отзыв сессии — одна операция.
Пул соединений и таймауты (уровень 4):
- `psycopg_pool.ConnectionPool(min_size=2, max_size=10, timeout=5.0)`, `statement_timeout=5000 ms` через `options`. Пул инициализируется в `lifespan` и закрывается на shutdown.
Keyset-пагинация (уровень 4):
- `list_messages_page(chat_id, limit, after)`: `WHERE chat_id = %s AND (created_at, id) > (%s, %s) ORDER BY created_at, id LIMIT %s`. Берётся `limit + 1`, чтобы определить наличие следующей страницы. Полного scan всей истории на страницу нет.
Аутентификация (lab1 → lab2):
- Регистрация `POST /api/v1/users` требует поле `password` (12–128 code points). Пароль хешируется стандартным `hashlib.scrypt` с уникальной солью на пользователя, формат хранения `scrypt$N$r$p$salt$dk`. Проверка через `hmac.compare_digest`.
- `POST /api/v1/auth/sessions` принимает только Basic `Authorization: Basic <base64(username:password)>`, без JSON body. Неверные креды → 401 с `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`.
- Успешный вход → 201 `{token, token_type="Bearer", expires_at, user}`. Токен — `secrets.token_urlsafe(32)`, хранится серверной сессией в таблице `sessions` с TTL из `SESSION_TTL_SECONDS` (по умолчанию 3600).
- Защищённые endpoint принимают только `Authorization: Bearer <token>`. Истёкший/отозванный/неизвестный токен → 401 с `WWW-Authenticate: Bearer realm="messenger"`.
- `DELETE /api/v1/auth/sessions/current` → отзыв текущей сессии. 204, повтор → 401.
- `X-User-Id` (lab1) с lab2 игнорируется и доступа не даёт: смоук проверяет, что с валидным Bearer и чужим `X-User-Id: <eve>` возвращается владелец токена (Alice), а не Eve.
- Согласно `contracts/README.md`, Basic на бизнес-endpoint → 401.
Обработка недоступности зависимостей:
- `psycopg.OperationalError` → 503 `{"error":{"code":"unavailable",...}}` (обработчик в `main.py`).
- Redis-ошибки в `sessions.py` обёрнуты в `RuntimeError("redis_unavailable: ...")`, `main.py` превращает в 503 `unavailable`.
- `/health/ready` пингует PostgreSQL и, в режиме `redis`, Redis; при ошибке исключение вылетает наверх и превращается в 503 с телом `Error`.
Дерево проекта (изменения относительно lab1 отмечены `*`):
```
mtusi2026lab2/
├── compose.yaml * # API + Redis, PostgreSQL на хосте
├── Dockerfile
├── Makefile
├── README.md, COURSE.md, ... # скелет без изменений
├── requirements.txt * # + psycopg_pool, redis
├── .env.example * # + REDIS_URL, SESSION_STORE
├── src/app/ # исходники приложения
│ ├── main.py * # точка входа uvicorn, init_pool/close_pool, 503-обработчики
│ ├── api/
│ │ ├── health.py * # readiness пингует PostgreSQL + Redis
│ │ ├── auth.py # Авторизация
│ │ ├── security.py
│ │ ├── users.py
│ │ ├── chats.py
│ │ └── messages.py * # keyset-пагинация в SQL
│ ├── models/schemas.py # Pydantic-схемы
│ └── storage/
│ ├── db.py * # ConnectionPool, SCHEMA_SQL, statement_timeout
│ ├── postgres.py * # PostgresStorage, делегаты сессий, list_messages_page
│ ├── sessions.py * # Redis-сессии, RuntimeError
│ └── memory.py # референс lab1, не используется
├── scripts/
│ ├── restart.sh * # Linux/CI: перезапуск API и Redis через compose
│ └── restart.bat * # Windows-эквивалент для локального прогона
├── student-tests/
│ ├── run_all.py
│ ├── test_negative.py
│ ├── test_concurrency.py
│ └── test_lab2_level4.py * # конкурентная регистрация, expiry, EXPLAIN, Redis down
└── tests/ # публичные проверки, без изменений
```
Что перенесено из lab1 без изменений: FastAPI-роутеры, Pydantic-схемы, middleware `X-Request-Id`, структурное логирование, обработчик SIGTERM, формат ошибок, Dockerfile (multi-stage, non-root, healthcheck), `.dockerignore`, `student-tests/test_negative.py`, `student-tests/test_concurrency.py`.
Что изменено:
- `requirements.txt`: добавлены `psycopg[binary]`, `psycopg_pool`, `redis`.
- `.env.example`: добавлены `REDIS_URL`, `SESSION_STORE`.
- `storage/db.py`: `connection()` берёт соединение из пула; `init_schema()` идемпотентен.
- `src/app/storage/postgres.py` — реализует тот же интерфейс, что `MemoryStorage`, плюс делегаты сессий и `list_messages_page`.
- `storage/sessions.py`: новый файл, хранилище сессий — Redis или PostgreSQL.
- `api/messages.py`: keyset-пагинация вынесена в SQL.
- `api/health.py`: readiness проверяет PostgreSQL и Redis.
- `main.py`: `init_pool`/`close_pool`, обработчики 503.
- `scripts/restart.sh`, `scripts/restart.bat`: перезапускают API и Redis.
- `student-tests/test_lab2_level4.py`: тесты уровня 4.
Соответствие `.env.example` реальной конфигурации:
- `APP_HOST`, `APP_PORT` — используются uvicorn/CMD в Dockerfile.
- `APP_ENV` — пишется в стартовый лог `event=startup app_env=...`, в остальном на логику не влияет.
- `SESSION_TTL_SECONDS` — TTL серверных сессий в таблице `sessions`, по умолчанию 3600.
- `DATABASE_URL` — строка подключения к PostgreSQL. В Docker используется `host.docker.internal` (PostgreSQL на хосте); пароль — в локальном `.env`, в `.env.example` — placeholder.
- `REDIS_URL` — адрес Redis в compose-сети (`redis://redis:6379/0`), не секрет.
- `SESSION_STORE` — `redis` (уровень 4) или `postgres` (fallback).
- `CACHE_URL_FILE` — резервная переменная из скелета, не используется.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | Уровень |
| --- | --- | --- | --- | --- |
| OpenAPI 3.1 и JSON Schema | `python scripts/validate_openapi.py` | `PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.` | evidence/lab2/lab2_checks.txt | **3** |
| Структура и локальные ссылки | `python scripts/check_contract.py` | `PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.` | evidence/lab2/lab2_checks.txt | **3** |
| Публичный smoke | `python tests/smoke.py --base-url http://localhost:8080` | `PASS: lab2 public API scenario; infrastructure and grading evidence remain separate.` | evidence/lab2/lab2_checks.txt | **3** |
| Собственные тесты lab1 | `python student-tests/run_all.py --base-url http://localhost:8080` | `PASS: all student tests (level 4) passed` | evidence/lab2/lab2_checks.txt | **3** |
| Dockerfile собирает приложение, слушает 0.0.0.0:8080 | `docker compose --env-file .env up -d --build` | `/health/ready` → `{"status":"ok"}` | evidence/lab2/lab2_checks.txt | **3** |
| PostgreSQL как источник истины | `init_schema()`; таблицы в pgAdmin | `users`, `chats`, `chat_members`, `messages`, `sessions` присутствуют | evidence/lab2/lab2_checks.txt | **3** |
| PK/FK, уникальность username, миграции с нуля | `SCHEMA_SQL` в `db.py`; прогон на пустой БД | таблицы создаются идемпотентно, повторный запуск не дублирует | evidence/lab2/lab2_checks.txt | **3** |
| Составная операция создания чата атомарна | `create_chat`: INSERT chats + INSERT chat_members в одной транзакции | при ошибке INSERT в `chat_members` чат не появляется | src/app/storage/postgres.py | **3** |
| Basic только на `POST /auth/sessions` | смоук: Basic на `/users/me` → 401; `X-User-Id` игнорируется | `PASS: lab2 public API scenario` | evidence/lab2/lab2_checks.txt | **3** |
| Срок жизни сессии и отзыв | `DELETE /auth/sessions/current` → 204; повтор → 401 | 204, затем 401 | evidence/lab2/lab2_checks.txt | **3** |
| X-User-Id не даёт доступ | `GET /users/me` с `Authorization: Bearer Alice` и `X-User-Id: <eve>` | возвращает Alice | evidence/lab2/lab2_checks.txt | **3** |
| Пароли хешируются password KDF | `hashlib.scrypt`, формат `scrypt$N$r$p$salt$dk` | plaintext/hash в ответах API не фигурируют | src/app/storage/postgres.py | **3** |
| Persistence: данные и сессия переживают рестарт API и Redis | `python tests/resilience.py --mode persistence --action-script scripts/restart.bat --base-url http://localhost:8080` | `PASS: persistence preserved confirmed data and existing session.` | evidence/lab2/lab2_persistence.txt | **3** |
| Hook реально перезапустил API и Redis | `docker inspect -f "{{.State.StartedAt}}"` до/после | время старта изменилось, данные сохранены | evidence/lab2/lab2_persistence.txt | **3** |
| Secrets/volumes не попадают в Git | `.dockerignore`, `.env` локально | `DATABASE_URL`/`REDIS_URL` в `.env.example` — плейсхолдеры | .env.example | **3** |
| Redis реально используется для сессий с TTL | `docker exec mtusi-redis redis-cli KEYS "sess:*"`, `TTL sess:<token>` | ключи `sess:*`, TTL ≈ `SESSION_TTL_SECONDS` | evidence/lab2/lab2_level4.txt | **4** |
| Redis persistence, выдерживающее рестарт | `docker exec mtusi-redis redis-cli INFO persistence`; рестарт Redis | `aof_enabled:1`; сессии живы после рестарта | evidence/lab2/lab2_level4.txt | **4** |
| Параметризованные запросы, ограниченный пул, таймауты | `psycopg_pool.ConnectionPool(2..10, timeout=5)`, `statement_timeout=5000` | нет `psycopg.connect()` на запрос | src/app/storage/db.py | **4** |
| Гонка регистрации одинакового username | `python student-tests/test_lab2_level4.py` (блок `test_concurrent_registration`) | ровно одна 201, остальные 409 | evidence/lab2/lab2_level4.txt | **4** |
| Индекс истории обоснован EXPLAIN на ≥10 000 сообщениях | тот же скрипт, `test_explain` | `Index Scan using idx_messages_chat_created` | evidence/lab2/lab2_level4.txt | **4** |
| Keyset-пагинация без полного scan на страницу | `list_messages_page` в `postgres.py` | `WHERE (created_at, id) > (…, …)` + `LIMIT` | src/app/storage/postgres.py | **4** |
| Автопроверка expiry при коротком TTL | `SESSION_TTL_SECONDS=5`, `test_short_ttl_expiry` | до TTL — 200, после — 401; повторный вход работает | evidence/lab2/lab2_level4.txt | **4** |
| Logout и неверный пароль | `DELETE /auth/sessions/current`; неверный Basic | 204 → 401; неверный Basic → 401 с Basic-challenge | evidence/lab2/lab2_checks.txt | **3** |
| Недоступность Redis не даёт анонимный доступ | `test_redis_unavailable` (stop redis → ready 503) | `/health/ready` → 503 `unavailable`, Bearer не проходит | evidence/lab2/lab2_level4.txt | **4** |
| Недоступность PostgreSQL → 503 | обработчик `psycopg.OperationalError` в `main.py` | 503 `unavailable`, без внутренних деталей | src/app/main.py | **4** |
| Выбранный трек 5 | не заявлен | — | — | — |
## Эксперименты и отказы
Hardware и версии:
- Windows 11, Docker Desktop (WSL2 backend), без лимитов CPU/RAM на контейнер;
- Образ `mtusi-messenger:lab2` на `python:3.12-slim`;
- PostgreSQL 18.6 на хосте
- Redis 7.4.1-alpine в Compose.
| Воздействие | Что ожидаем | Что наблюдали | Восстановление / потери |
| --- | --- | --- | --- |
| `docker compose restart api redis` (`scripts/restart.bat`) | API и Redis перезапускаются, PostgreSQL и volumes не трогаются; прежний Bearer читает прежние данные | `PASS: persistence preserved confirmed data and existing session`; `event=startup` в логах, `StartedAt` изменился | downtime ≈ 2–3 с; потери 0 |
| `docker compose stop redis`, затем запрос `/health/ready` | 503 `unavailable`, анонимный доступ не открывается | `PASS: readiness 503 без Redis`; после `start redis` — 200 | downtime ≈ 3 с; потери сессий 0 (AOF) |
| Повторный `init_schema()` | Идемпотентно, без дублирования, таблицы уже существуют | ошибок нет, нет дублирования строк | — |
| SIGTERM (`docker stop -t 10`) | завершение ≤ 10 с | как в lab1: <1 с, `event=shutdown_complete` | — |
Профиль нагрузки на lab2 не снимался: на уровне 3/4 нагрузочные измерения не требуются, EXPLAIN на ≥10 000 сообщениях подтверждает индекс запроса истории.
## Ограничения и следующие шаги
Что выдерживает реализация:
- Штатную работу API с PostgreSQL (источник истины) и Redis (сессии с TTL и AOF).
- Регистрацию (scrypt), Basic → Bearer, TTL, отзыв, повторный вход.
- Сохранение пользователей, чатов, членства, сообщений и действующих сессий при рестарте API и Redis без удаления volumes.
- Атомарность создания чата (INSERT chats + INSERT chat_members в одной транзакции); идемпотентную миграцию.
- Keyset-пагинацию в SQL с индексом `idx_messages_chat_created`.
- Контрактные ответы, `X-Request-Id`, `WWW-Authenticate`, 503 при недоступности Redis/PostgreSQL.
- Конкурентную регистрацию одинакового username без дублей.
Учебные упрощения:
- PostgreSQL запущен на хосте (не в Compose); в коде это только DSN, перенос в Compose не требует правок.
- `storage/memory.py` оставлен как референс lab1 и в приложении не используется.
- `SESSION_STORE=postgres` — fallback, оставлен для сравнения; в рабочем режиме — `redis`.
Что не входит в уровень 4:
- Горизонтальное масштабирование, балансировщик, HA (lab3+).
- Вложения и S3 (lab4+), фоновая обработка (lab5+), OTel/Grafana (lab6+), TLS/mTLS/OpenBao/Argon2id (lab7).
- Трек 5 не заявлен.
Следующие шаги (при заявке на 5):
1. Трек 1 «Согласованность кэша»: cache-aside поверх PostgreSQL с измерением SQL-запросов/latency до и после, защита от stampede, read-after-write.
2. Либо Трек 2 «План запроса и восстановление»: ≥100 000 сообщений, сравнение ≥2 индексов, backup → restore → сверка.
```