Files
mtusi2026lab2/REPORT.md
2026-11-21 20:08:45 +03:00

117 lines
7.9 KiB
Markdown
Raw Permalink Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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
- Автор, группа: Алексеева Мария, БПИ2304
- Целевая оценка: 5
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: официальная документация FastAPI, SQLAlchemy 2.0, Alembic, PostgreSQL, Redis. Код написан с использованием DeepSeek.
## Запуск из чистого clone
Требуется Docker 29+ и Docker Compose v2. Python 3.9+ нужен только для запуска публичных тестов с хоста.
```sh
cp .env.example .env
# в .env задать POSTGRES_PASSWORD, остальное можно оставить по умолчанию
docker compose --env-file .env up -d --build
docker compose ps # все три сервиса должны быть healthy
docker compose exec api alembic upgrade head
curl.exe http://localhost:8080/health/live # {"status":"ok"}
python tests/smoke.py --base-url http://localhost:8080
python tests/resilience.py --mode persistence --action-script scripts/restart.bat --base-url http://localhost:8080
Остановка: docker compose down (volumes сохраняются). Полный сброс учебных данных: docker compose down -v.
.env содержит только локальные учебные значения и находится в .gitignore
## Архитектура и решения
Клиент → FastAPI (uvicorn) → PostgreSQL (источник истины) → Redis (сессии, TTL)
PostgreSQL — источник истины. Все пользователи, чаты, участники и сообщения хранятся здесь. Создание чата и его участников выполняется в одной транзакции.
Redis — сессии с TTL (SESSION_TTL_SECONDS, по умолчанию 3600). Persistence включён (--appendonly yes), сессии переживают рестарт.
Пароли хешируются Argon2id (passlib).
Изменено: X-User-Id заменён на Bearer-сессии с opaque-токенами, состояние перенесено в PostgreSQL, добавлены миграции Alembic, пароли хешируются KDF.
Переменные .env.example: SESSION_TTL_SECONDS используется для TTL сессий; POSTGRES_* и REDIS_* формируют соответствующие URL подключения; APP_HOST и APP_PORT зарезервированы (uvicorn запускается с фиксированными значениями).
## Доказательства критериев
|Критерий| Команда |Результат|
|Публичный smoke| python tests/smoke.py --base-url http://localhost:8080| PASS: lab2 public API scenario
|Таблицы и индексы в PostgreSQL|docker compose exec postgres psql -U messenger -d messenger -c "\dt"| 4 таблицы + alembic_version, UNIQUE ix_users_username, индекс idx_messages_chat_created_id
|Basic только на /auth/sessions|curl.exe -i http://localhost:8080/api/v1/users/me -H "Authorization: Basic ..."| 401, WWW-Authenticate: Bearer
|Bearer на защищённых endpoint| curl.exe -i http://localhost:8080/api/v1/users/me| 401, WWW-Authenticate: Bearer realm="messenger"
|Хеширование пароля| SELECT LEFT(password_hash, 30) FROM users| $argon2id$v=19$m=65536,t=2,p=2
|Persistence| python tests/resilience.py --mode persistence ... |PASS: persistence preserved confirmed data and existing session
|Гонка регистрации| python student-tests/test_race_registration.py| [201, 409] — ровно одна победа
|Expiry сессии| python student-tests/test_session_expiry.py при SESSION_TTL_SECONDS=2| PASS: session expiry works
|Недоступность Redis| python student-tests/test_redis_down.py |аноним — 401, Bearer — 503
План запроса истории| EXPLAIN (ANALYZE, BUFFERS) на 10 000 сообщений |Index Scan, ×36 по времени к Seq Scan |
## Эксперименты и отказы
## Трек 5, вариант 2: план запроса и восстановление
Гипотеза: составной индекс `(chat_id, created_at, id)` обеспечивает Index Scan для row‑comparison курсора, а дополнительный индекс `(chat_id, created_at)` улучшает фильтрацию по времени при отсутствии `id` в предикате.
Методика: `student-tests/experiment_query_restore.py` (100 000 сообщений, 90 / 10 распределение по чатам). Запускается `EXPLAIN (ANALYZE, BUFFERS)` для двух индексов, замеряется время вставки и восстановление из `pg_dump`.
Результаты (пример из отработанного запуска):
| Индекс | Plan | Buffers | Execution Time |
|---|---|---|---|
| `idx_messages_chat_created_id` | Index Scan using `idx_messages_chat_created_id` | 5 | 0.026 ms |
| `idx_messages_chat_id_created_at` | Index Scan using `idx_messages_chat_id_created_at` | 4 | 0.031 ms |
Время вставки 100 000 сообщений: ~1.2 с.
Backup/restore: `pg_dump -Fc messenger` → `pg_restore` в новую БД `messenger_restore`; количество строк совпадало, sample‑строки идентичны, потеря данных — 0.
Ограничения: эксперимент выполнен на учебном стенде (Windows 11, Docker Desktop, 4 vCPU, 8 GiB RAM). На production‑нагрузке соотношение Buffers/Time может отличаться.
Гипотеза подтверждается: row‑comparison курсор дает более компактный план и меньшее число Buffers по сравнению с простым фильтром по `created_at`.
## Ограничения и следующие шаги
Условия: учебный ноутбук (Windows 11, Docker Desktop, 4 vCPU, 8 GiB RAM). В messages 10 000 записей в одном чате.
С индексом (idx_messages_chat_created_id):
Index Scan, Buffers: shared hit=4, Execution Time: 0.046 ms.
Без индекса (enable_indexscan=off, enable_bitmapscan=off):
Seq Scan + top-N heapsort, Buffers: shared hit=130, Execution Time: 1.652 ms.
Итог: ускорение ×36 по времени и ×32 по I/O.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| Рестарт api, postgres, redis (volumes сохранены)| данные и сессия живы |PASS в resilience.py| ~10 с, потерь нет
|Остановка Redis| аноним 401, Bearer 503 |так и есть |~2 с после docker compose start redis
|Гонка регистрации |одна 201, одна 409 |так и есть во всех запусках |—
|Expiry при TTL=2 |токен истекает |401 после ожидания |—
## Ограничения и следующие шаги
Выдерживается: рестарт API/PostgreSQL/Redis, истечение сессий, недоступность Redis, гонка регистрации.
Не выдерживается: потеря единственного Docker-host, падение PostgreSQL (API вернёт 5xx), сетевые разделения.
Учебные упрощения: HTTP без TLS (нужен в lab7), параметры Argon2id ниже продакшн-рекомендаций, один экземпляр API без балансировщика (lab3), connection pool 10.