forked from mtusi2026/mtusi2026lab2
REPORT.md
This commit is contained in:
@@ -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`.
|
||||
Reference in New Issue
Block a user