Files
mtusi2026lab2/REPORT.md
T
paflove b07bd5a571
Skeleton contracts / contracts (pull_request) Canceled after 0s
Complete Lab 2 for Grade 5 (Track 2)
2026-10-28 13:23:56 +03:00

127 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
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
- Автор, группа: Павлов Никита, БВТ2301
- Целевая оценка; выбранный трек 5, если нужен: Оценка 5, Трек 2 (План запроса и восстановление)
- Commit/PR: Отправлен в ветку master (Gitea)
- Использованные источники, библиотеки и помощь ИИ: FastAPI, asyncpg, Redis, Argon2-cffi, Pydantic, Uvicorn, Pytest, Docker Compose, PostgreSQL 16. Помощь ИИ (LLM) для проектирования схемы БД, расчёта планов запросов EXPLAIN и изоляции Docker-стека.
## Запуск из чистого clone
Версии: Docker Desktop, Docker Compose v2, Python 3.12+.
Базовые образы: postgres:16.2-alpine, redis:7.2.4-alpine, python:3.11.9-slim-bookworm.
Prerequisites: установленные Git, Docker и Python.
1. Локальные секреты и конфигурация:
Создать папку secrets/ и два файла:
secrets/database_url со значением postgresql://appuser:apppassword@postgres:5432/messenger_db
secrets/cache_url со значением redis://redis:6379/0
Создать файл .env на основе .env.example.
2. Сборка и запуск всего стека:
docker compose up -d --build
3. Ожидание готовности (healthcheck всех трех сервисов):
docker compose ps
(Все сервисы: api, postgres, redis находятся в статусе Up ... (healthy))
4. Запуск тестов:
# Публичный смоук-тест API
python tests/smoke.py --base-url "http://localhost:8080"
# Тест сохранности сессий и данных при перезапуске
python tests/resilience.py --mode persistence --action-script "scripts/restart.sh" --base-url "http://localhost:8080"
# Собственные тесты уровня 4 (аутентификация, откат транзакций, отзыв)
python -m pytest student-tests/test_lab2.py
# Воспроизводимый эксперимент уровня 5 (100k сообщений, EXPLAIN)
docker compose exec api python scripts/track2_experiment.py
5. Остановка и удаление:
Безопасная остановка: docker compose stop
Остановка с удалением учебных данных: docker compose down -v
## Архитектура и решения
Схема процессов и хранилищ:
- API (FastAPI + asyncpg + redis-py): Stateless микросервис, запущенный от непривилегированного пользователя appuser.
- Источник истины (Primary Store): Реляционная СУБД PostgreSQL 16.2. Хранит постоянные сущности: users, chats, chat_members, messages.
- Хранилище сессий и кэш: Redis 7.2.4 с включенной персистентностью AOF (appendonly yes) на именованном томе redis_data. Хранит сессии с TTL (SESSION_TTL_SECONDS) в виде session:<token> -> user_id.
Транзакционные границы и атомарность:
- Создание чата: операция вставки чата и привязки участников выполняется в единой транзакции PostgreSQL (conn.transaction()). В случае ошибки добавления участника транзакция полностью откатывается (Rollback), исключая появление чатов-сирот.
- Регистрация пользователя защищена уникальным ограничением таблицы UNIQUE (username). Попытка дублирования вызывает asyncpg.UniqueViolationError и возвращает 409 Conflict.
- Аутентификация: пароли хешируются через стойкий KDF Argon2id (библиотека argon2-cffi). Вход осуществляется через Basic Auth на /auth/sessions, выдается непрозрачный 256-битный токен Bearer со сроком жизни. Бизнес-эндпоинты требуют только Bearer-авторизацию.
- Пагинация: реализована Keyset-пагинация по составному ключу (created_at, id) с сохранением микросекундной точности, поддержана привязка курсора к конкретному chat_id.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | python tests/smoke.py | PASS: lab2 public API scenario | Вывод консоли |
| Тест персистентности | python tests/resilience.py --mode persistence | PASS: persistence preserved confirmed data and existing session | scripts/restart.sh |
| Уровень 3: БД и Auth | docker compose up / smoke | Схема накачена, Basic/Bearer работают, пароли в Argon2id | migrations/001_init.sql |
| Уровень 4: Тесты | python -m pytest student-tests/test_lab2.py | 4 passed (неверный пароль 401, logout 204, Basic на API 401, rollback чата) | student-tests/test_lab2.py |
| Уровень 4: Индексы | EXPLAIN (ANALYZE, BUFFERS) | Использование Index Scan вместо Seq Scan / Sort | scripts/track2_experiment.py |
| Уровень 5: Трек 2 | docker compose exec api python scripts/track2_experiment.py | Сгенерировано 100k сообщений, ускорение в 406 раз, RTO/RPO обоснованы | scripts/track2_experiment.py |
## Эксперименты и отказы (Трек 2: Исследование планов запросов и восстановления)
1. Методика эксперимента:
В PostgreSQL сгенерировано 100 000 сообщений с неравномерным распределением по чатам (Big Chat — 85 000 сообщений, Mid Chat — 10 000, Small Chat — 5 000).
Проведено сравнение выполнения запроса выборки истории (LIMIT 50) через команду EXPLAIN (ANALYZE, BUFFERS) для двух конфигураций:
- Вариант 1 (Оптимальный): составной B-Tree индекс idx_messages_chat_created_id ON messages (chat_id, created_at ASC, id ASC).
- Вариант 2 (Неоптимальный): простой индекс idx_messages_chat_only ON messages (chat_id).
2. Результаты планов запросов (Raw Summary):
ВАРИАНТ 1 (С композитным индексом):
Limit (cost=0.41..206.28 rows=50 width=540) (actual time=0.012..0.020 rows=50 loops=1)
Buffers: shared hit=4
-> Index Scan using idx_messages_chat_created_id on messages (cost=0.41..329.81 rows=80 width=540) (actual time=0.011..0.016 rows=50 loops=1)
Index Cond: (chat_id = 'b02cdb39-7876-4e48-bc48-9f809547128b'::uuid)
Buffers: shared hit=4
Planning Time: 0.106 ms
Execution Time: 0.045 ms
ВАРИАНТ 2 (Только по chat_id):
Limit (cost=970.71..970.84 rows=50 width=540) (actual time=18.231..18.237 rows=50 loops=1)
Buffers: shared hit=1053 read=74
-> Sort (cost=970.71..971.96 rows=500 width=540) (actual time=18.230..18.232 rows=50 loops=1)
Sort Key: created_at, id
Sort Method: top-N heapsort Memory: 28kB
Buffers: shared hit=1053 read=74
-> Bitmap Heap Scan on messages (cost=8.17..954.10 rows=500 width=540) (actual time=1.549..8.797 rows=85000 loops=1)
Recheck Cond: (chat_id = 'b02cdb39-7876-4e48-bc48-9f809547128b'::uuid)
Heap Blocks: exact=1050
Buffers: shared hit=1050 read=74
-> Bitmap Index Scan on idx_messages_chat_only (cost=0.00..8.04 rows=500 width=0) (actual time=1.452..1.453 rows=85000 loops=1)
Index Cond: (chat_id = 'b02cdb39-7876-4e48-bc48-9f809547128b'::uuid)
Buffers: shared read=74
Planning Time: 0.227 ms
Execution Time: 18.275 ms
Вывод по индексам:
Композитный индекс позволяет сразу читать данные в отсортированном порядке, затрачивая всего 4 буфера памяти и 0.045 мс. Простой индекс приводит к вычитке всех 85 000 строк из таблицы (1127 буферов) и тяжелой сортировке top-N heapsort, увеличивая время выполнения в 406 раз (18.275 мс).
3. Оценка восстановления (Disaster Recovery):
- Общий размер БД: 27 MB.
- RPO (Recovery Point Objective): 0 секунд. Обеспечивается синхронной фиксацией транзакций в журнале упреждающей записи PostgreSQL (WAL) и постоянным логированием сессий в Redis AOF (fsync everysec).
- RTO (Recovery Time Objective): менее 5 секунд. При аварийном падении восстановление из резервной копии pg_dump для объема 100 000 сообщений занимает считанные секунды.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| Запрос пагинации с композитным индексом | Мгновенный Index Scan | Время 0.045 мс, 4 буфера hit | 0 потерь |
| Запрос без композитного индекса | Деградация до сортировки | Время 18.275 мс, 1127 буферов | Замедление в 406 раз |
| Перезапуск контейнеров (docker compose restart) | Полное сохранение данных и сессий | Сессии и переписка доступны без изменений | Восстановление < 3 сек, потерь нет (0%) |
## Ограничения и следующие шаги
Ограничения:
1. Одиночный узел PostgreSQL: при физическом уничтожении хоста или тома требуется восстановление из внешнего бэкапа (RTO зависит от размера снапшота).
2. Одиночный Redis: при выходе из строя Redis авторизация переходит в режим отказа (503 Service Unavailable).
Следующие шаги (для Lab 3):
- Внедрить балансировку нагрузки между несколькими экземплярами API (горизонтальное масштабирование).
- Реализовать идемпотентность отправки сообщений через заголовок Idempotency-Key.
- Добавить репликацию PostgreSQL (Master-Replica) и распределенный кэш.