REPORT.md

This commit is contained in:
2026-10-02 22:38:25 +03:00
parent 43e5964180
commit 95d89194e8
+170 -23
View File
@@ -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: <uuid>` | `Authorization: Bearer <token>` |
| Регистрация | `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:<sha256(token)>` →
`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`.