diff --git a/REPORT.md b/REPORT.md index e42f2b05..95aaf136 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,184 @@ # Отчёт — лабораторная 2 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор, группа: Максимова Снежана, БПИ2302 +- Целевая оценка: 5, трек A (согласованность кэша) +- Commit/PR: +- Источники и ИИ: FastAPI 0.110.0, SQLAlchemy 2.0.29 (async), asyncpg 0.29.0, + Alembic 1.13.1, bcrypt 4.1.2, redis-py 5.0.3, Pydantic 2.6.4. ИИ использовался + для черновика кода, финальный код проверен вручную. -## Запуск из чистого clone +## 1. Что изменилось относительно lab1 -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +В lab1 сервер держал всё состояние в памяти процесса и терял его при +перезапуске. В lab2 задача — сделать данные и сессии долговечными, а также +заменить учебный `X-User-Id` на настоящую аутентификацию. -## Архитектура и решения +Конкретные переходы API между лабами (объявлены в `COURSE.md`): -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +| Что | Lab1 | Lab2 | +|---------------|-------------------------|----------------------------------------| +| Хранилище | `dict` в памяти | PostgreSQL | +| Идентификация | `X-User-Id: ` | `Authorization: Bearer ` | +| Регистрация | `username, display_name`| `+ password` (12–128 символов) | +| Логин | нет | `POST /auth/sessions` (Basic → Bearer) | +| Logout | нет | `DELETE /auth/sessions/current` | +| Сессии | нет | TTL через `SESSION_TTL_SECONDS` | -## Доказательства критериев +Код приложения перенесён из lab1 и переработан: `main.py` переписан под +PostgreSQL, `storage.py` удалён, добавлены `db/`, `repositories/`, `auth.py`. -| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | -| --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +## 2. Архитектура -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +Клиент → API (FastAPI + uvicorn) → PostgreSQL + Redis. -## Эксперименты и отказы +- **PostgreSQL** — пользователи, чаты, членство, сообщения. +- **Redis** — быстрый слой для сессий (с TTL) и кэша первой страницы истории. +- **Alembic** — версионируемые миграции схемы. +- **Docker Compose** — единый локальный запуск: `postgres`, `redis`, `api`. +- API работает под непривилегированным пользователем `appuser` (UID 10001), + слушает `0.0.0.0:8080`, PID 1 — uvicorn. -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +## 3. Схема БД -| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | -| --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| Таблица | Поля | Ключи | Индекс | +|---------------|-------------------------------------------------------|----------------------------------|-----------------------------| +| `users` | id, username, display_name, password_hash, created_at | username UNIQUE | `idx_users_username` | +| `chats` | id, title, created_at | — | `idx_chats_created_id` | +| `chat_members`| chat_id, user_id | PK(chat_id, user_id), FK CASCADE | `idx_chat_members_user` | +| `messages` | id, chat_id, sender_id, text, created_at | FK CASCADE |`idx_messages_chat_created_id`| +| `sessions` | id, user_id, token_hash, expires_at, created_at | token_hash UNIQUE | `idx_sessions_token`, | +| | | `idx_sessions_expires` | -## Ограничения и следующие шаги +**Почему такие индексы:** -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +- `idx_messages_chat_created_id(chat_id, created_at, id)` — ключевой для пагинации. Запрос истории всегда фильтрует по `chat_id` и + сортирует по `(created_at, id)`. Составной индекс покрывает обе операции. +- `idx_chat_members_user` — для «списка чатов пользователя». +- `idx_chats_created_id` — для keyset-пагинации в `GET /chats`. +- `idx_sessions_token` — поиск сессии на каждом защищённом запросе. + +**Транзакционные границы:** + +- **Регистрация** — одна транзакция. От гонки на одинаковый username защищает + UNIQUE-constraint: второй параллельный запрос получает `IntegrityError`, + который превращается в 409. +- **Создание чата с участниками** — одна транзакция: сначала проверяем, что все + `member_ids` существуют, затем `INSERT` чата, потом `INSERT` участников. Если + хотя бы один участник не существует — `rollback`, ничего не создаётся. +- **Отправка сообщения** — одна транзакция. + +## 4. Идентификация и сессии + +- **Регистрация** принимает `password` (12–128 code points). Пароль хешируется + через **bcrypt(SHA-256(password))**. Предварительное SHA-256 снимает + ограничение bcrypt в 72 байта и проблему NUL-байт в дайджесте. +- **Basic** применяется только на `POST /auth/sessions`. Неверные credentials — + 401 с `WWW-Authenticate: Basic realm="messenger", charset="UTF-8"`. +- **Bearer** — все остальные endpoint. Токен — opaque, 32 байта энтропии + (`secrets.token_urlsafe(32)`). В Redis хранится `session:` → + `user_id` с TTL = `SESSION_TTL_SECONDS`. +- **Logout** удаляет ключ из Redis. Повторный вызов с тем же токеном — 401. +- **`X-User-Id` игнорируется** — он не даёт доступ к бизнес-эндпоинтам. + +## 5. Доказательства критериев + +| Критерий | Команда | Результат | +|----------------------|-------------------------------------------------|---------------------------| +| Публичный smoke | `python tests\smoke.py` | PASS | +| Persistence | `python tests\resilience.py --mode persistence` | PASS | +| Concurrent (100/100) | `python student-tests\concurrent_test.py` | PASS | +| Rollback и race | `pytest student-tests/` | 3 passed | +| Non-root | `docker inspect Config.User` | `10001` | +| SIGTERM ≤ 10 c | `docker stop` | ~1 c | +| Healthcheck | `docker ps` | `Up (healthy)` | +| EXPLAIN с индексом | `EXPLAIN (ANALYZE, BUFFERS)` | Index Scan, 0.069 ms | +| EXPLAIN без индекса | `enable_indexscan=off` | Seq Scan + Sort, 1.398 ms | +| Session expiry | `SESSION_TTL_SECONDS=2` | 401 после TTL | +| Трек A | `scripts\track_a_bench.py` | SQL 301 → 1 | + +## 6. Эксперименты + +### 6.1. Обоснование индекса истории + +**Зачем измеряли.** README lab2 требует: «Индекс истории обоснован запросом и +EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщениях; пагинация не использует +полный scan всей истории на каждую страницу.» Мы засеяли чат 8 837 сообщений +через `scripts/seed_10k.py` и сняли план для запроса истории. + +**Результаты:** + +| План | Buffers | Execution Time | Что делает | +|-----------------------------------------------------|---------|----------------|-------------------------------------| +| **Index Scan** using `idx_messages_chat_created_id` | **3** | **0.069 ms** | идёт напрямую по индексу | +| Seq Scan + Sort (индекс выключен) | 116 | 1.398 ms | читает всю таблицу, потом сортирует | + +**Вывод:** составной индекс `(chat_id, created_at, id)` делает чтение страницы +`O(limit)`, а не `O(n log n)`. Разница по чтению страниц — **~38×**, по времени +— **~20×**. С ростом объёма разрыв увеличивается линейно. + +### 6.2. Session expiry + +README требует «автоматическая проверка expiry при коротком +SESSION_TTL_SECONDS». + +**Методика.** `SESSION_TTL_SECONDS=2`, пересоздали api, создали сессию, +сразу же проверили `GET /users/me` (200), подождали 4 секунды, снова проверили +с тем же токеном. + +**Результат:** + +| Момент | Ответ | +|--------------------|------------------------------------------------| +| сразу после логина | 200 | +| через 4 секунды | 401 `{"error": {"code": "unauthorized", ...}}` | + +Это подтверждает: TTL работает, истёкший токен отвергается. + +### 6.3. Трек A — кэш первой страницы истории + +**Гипотеза.** Если кэшировать первую страницу истории в Redis, повторные +чтения не будут обращаться к БД. Инвалидация при вставке нового сообщения +(`create_and_invalidate`) гарантирует, что следующий GET после POST видит +новое сообщение (read-after-write). + +**Методика.** `scripts/track_a_bench.py` засеивает чат N сообщениями, затем +делает M последовательных GET первой страницы. Число SQL-запросов к `messages` +считается через `pg_stat_statements` (`pg_stat_statements_reset()` до замера, +чтение счётчика после). Два прогона: с `list_page` (без кэша) и с +`list_page_cached` + `create_and_invalidate`. + +**Результаты (N=1000, M=300):** + +| Метрика | До кэша | После кэша | Изменение | +|---------------------------|---------|------------|---------------| +| SQL-запросов к `messages` | **301** | **1** | ×301 меньше | +| p50, ms | 30.15 | 30.88 | без изменений | +| p95, ms | 34.92 | 33.55 | −4% | +| RPS | 40.65 | 35.39 | −13% | + +**Что это значит.** + +- Кэш **сократил обращения к БД в 301 раз**: 300 GET → 1 SELECT +- **Latency и RPS не улучшились**, потому что на этом профиле SQL-запрос уже + занимает 0.07 ms (по EXPLAIN), а Redis-roundtrip + JSON-сериализация + сравнимы или превышают сэкономленное время. Снижение RPS на 13% — прямое + следствие этого: кэш добавляет работу, которую SQL-запрос не оправдывает. +- **Кэш первой страницы — оптимизация нагрузки на БД, не скорости клиента.** + Эффект по latency проявился бы при росте датасета до 100k+, отсутствии + индекса, либо при конкуренции, упирающейся в connection pool Postgres. + На текущем профиле главная польза — разгрузка БД. + +## 7. Что пришлось чинить в процессе + +- **`async with db.begin()` конфликтует с неявной транзакцией.** В async + SQLAlchemy любой `await db.execute(...)` уже открывает транзакцию. Если + до этого сработал `Depends(get_current_user)` с SELECT, `db.begin()` + падает с `InvalidRequestError`. Решение: явный `try: commit / except: rollback` + без `db.begin()`. +- **bcrypt и NUL-байты.** `sha256(...).digest()` иногда содержит `\x00`, + и bcrypt отказывается с этим работать. Решение: `hexdigest()` — только + `[0-9a-f]`, 64 безопасных символа. +- **httpx через docker-proxy на Windows.** Часть POST-запросов из pytest + на хосте возвращала 503 с пустым телом, не доходя до uvicorn. `urllib` + и запуск тестов изнутри контейнера работают стабильно. Решение: собственные + тесты переведены на `urllib` — это описано в `student-tests/test_rollback.py`. \ No newline at end of file