Files
mtusi2026lab2/REPORT.md
T

24 KiB
Raw Blame History

Отчёт — лабораторная 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 создать роль приложения:
    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 → сверка.