Files
mtusi2026lab2/REPORT.md
T
2026-10-08 02:08:08 +03:00

173 lines
15 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
- **Автор, группа:** Травкин С.А., БВТ2304.
- **Целевая оценка; выбранный трек 5, если нужен:** 4. Трек 5 пока не заявлен.
- **Commit/PR:** указать после публикации.
- **Использованные источники, библиотеки и помощь ИИ:** README и API-контракт лабораторной; документация PostgreSQL, Redis, SQLAlchemy, Alembic, FastAPI и Docker Compose. Использованы Python, FastAPI, SQLAlchemy, asyncpg, Alembic, PostgreSQL 17.6, Redis 8.2.2, Argon2id. ChatGPT использовался для разбора задания, разработки и проверки реализации, тестов и оформления отчёта.
## Запуск из чистого clone
Необходимы Docker Engine, Docker Compose, Git и Python 3.9+ для публичных тестов. Приложение запускается в контейнерах; локально использовался Python 3.13.
После клонирования репозитория перейти в его каталог и создать локальную конфигурацию:
```bash
cp .env.example .env
mkdir -p secrets
chmod 700 secrets
```
Создать согласованные файлы секретов:
```bash
python3 - <<'PY'
from pathlib import Path
import secrets
directory = Path("secrets")
password = secrets.token_hex(24)
values = {
"postgres_password": password,
"database_url": f"postgresql+asyncpg://lab2:{password}@postgres:5432/messenger",
"cache_url": "redis://redis:6379/0",
}
for name, value in values.items():
path = directory / name
path.write_text(value, encoding="utf-8")
path.chmod(0o600)
print("Local secrets created.")
PY
```
Секреты создаются только при первоначальной настройке пустой базы. Пароли и строки подключения не выводятся в терминал и не добавляются в Git.
Сборка и запуск:
```bash
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
```
Используются образы PostgreSQL 17.6 и Redis 8.2.2. API собирается из локального `Dockerfile`. Сервис `migrate` автоматически выполняет `alembic upgrade head` после готовности PostgreSQL. API запускается после успешного завершения миграций и готовности Redis.
Проверка:
```bash
docker compose ps -a
curl -i http://localhost:8080/health/ready
make check
make test
```
Ожидаемый ответ `/health/ready` — HTTP 200, `{"status":"ok"}`.
Дополнительные проверки:
```bash
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
make validate PYTHON=.venv/bin/python
make test-persistence ACTION_SCRIPT=scripts/restart.sh
```
Собственные тесты:
```bash
python tests_student/test_auth.py
python tests_student/test_race.py
./scripts/test_short_ttl.sh
./scripts/test_failures.sh
```
Откат транзакции проверяется внутри контейнера:
```bash
docker compose run --rm --no-deps \
-e PYTHONPATH=/app \
-v "$PWD/tests_student:/app/tests_student:ro" \
api python tests_student/test_rollback.py
```
Безопасная остановка с сохранением данных:
```bash
docker compose down
```
Намеренное удаление учебных данных вместе с volumes:
```bash
docker compose down -v
```
## Архитектура и решения
Схема: **клиент → FastAPI → PostgreSQL / Redis**.
PostgreSQL — источник истины для пользователей, чатов, участников и сообщений. Redis используется для хранения сессий с TTL.
В PostgreSQL созданы таблицы `users`, `chats`, `chat_members`, `messages`. Используются UUID, первичные и внешние ключи, уникальность `username`. Для истории сообщений создан индекс `(chat_id, created_at, id)`.
Создание чата и добавление участников выполняются в одной транзакции. При ошибке изменения откатываются. Это проверено тестом `test_rollback.py`.
Из лабораторной № 1 сохранены основные операции мессенджера. Вместо хранения данных в памяти используется PostgreSQL. Добавлены пароли с Argon2id, вход через Basic, случайные Bearer-токены, TTL и logout. Заголовок `X-User-Id` больше не предоставляет доступ.
Redis хранит ключи `session:<token>` с UUID пользователя. При logout ключ удаляется, при истечении TTL становится недействительным. Включены AOF (`appendonly yes`, `appendfsync everysec`) и named volume `redis_data`. PostgreSQL использует named volume `postgres_data`.
SQL-запросы параметризованы. Пул SQLAlchemy: `pool_size=5`, `max_overflow=5`, `pool_timeout=5` секунд, таймаут подключения — 5 секунд. Для Redis установлены таймауты подключения и операций по 5 секунд.
Соответствие `.env.example` конфигурации: `APP_HOST`, `APP_PORT`, `APP_ENV`, `SESSION_TTL_SECONDS`, `DATABASE_URL_FILE`, `SESSION_STORE`, `CACHE_URL_FILE` передаются сервису API через Compose. URL подключений читаются из файлов `/run/secrets/database_url` и `/run/secrets/cache_url`. Пароль PostgreSQL читается из `/run/secrets/postgres_password`. Значение `SESSION_STORE=redis` соответствует используемому хранилищу сессий.
Миграции Alembic запускаются отдельным сервисом `migrate`. Проверен запуск на пустых volumes и создание схемы с нуля.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | `make test` | PASS, публичный API-сценарий выполнен | `evidence/grade4_checks.txt` |
| Проверка структуры и контракта | `make check`, `make validate` | Обе проверки PASS | `evidence/grade4_checks.txt` |
| Постоянное хранение данных и сессий | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | Данные и прежний токен сохранились | `evidence/grade4_resilience.txt` |
| Перезапуск всех сервисов | `scripts/restart.sh` | `docker compose down` и `up -d` без удаления volumes; ожидание готовности PostgreSQL, Redis и API | `scripts/restart.sh` |
| PostgreSQL, ключи и ограничения | `alembic upgrade head`, запуск с пустыми volumes | Схема создана, таблицы и ограничения применены | `migrations/versions/f7c51e1e945b_initial_schema.py` |
| Атомарность создания чата | `test_rollback.py` | PASS, частичные изменения отсутствуют | `evidence/grade4_checks.txt` |
| Basic, Bearer, неверный пароль и logout | `test_auth.py`, `make test` | Неверный пароль — 401; logout — 204; отозванный токен — 401 | `evidence/grade4_checks.txt` |
| Redis для сессий с TTL и persistence | Перезапуск Redis в `test_failures.sh` | Прежний действующий токен работает после восстановления | `evidence/grade4_resilience.txt` |
| Ограниченный пул и таймауты | Конфигурация SQLAlchemy и Redis | Пул 5+5, таймауты заданы | `src/database.py`, `src/sessions.py` |
| Конкурентная регистрация | `test_race.py` | Одна регистрация — 201, вторая — 409 | `evidence/grade4_checks.txt` |
| Индекс истории и пагинация | `EXPLAIN (ANALYZE, BUFFERS)` на 20 000 сообщениях | Keyset: 100 строк Index Scan против 15 100 у OFFSET | `evidence/explain_history.txt` |
| Короткий TTL | `test_short_ttl.sh` | Токен истёк, получен 401 | `evidence/grade4_resilience.txt` |
| Отказ Redis | `test_failures.sh` | Readiness — 503, защищённый запрос — 503, после восстановления — 200 | `evidence/failure_timings.txt` |
| Отказ PostgreSQL | `test_failures.sh` | Readiness — 503, защищённый запрос — 503, после восстановления — 200 | `evidence/failure_timings.txt` |
| Секреты вне Git | Проверка `.gitignore` | `.env`, `secrets/`, volumes и backups исключены | `.gitignore` |
## Эксперименты и отказы
**Эксперимент с индексом.** Гипотеза: keyset-пагинация с составным индексом эффективнее OFFSET при чтении глубокой страницы истории. Подготовлено 20 000 синтетических сообщений одного чата. После `ANALYZE` выполнены два запроса с `EXPLAIN (ANALYZE, BUFFERS)` для получения 100 сообщений после первых 15 000.
Результаты: OFFSET — 1,908 мс, 435 shared buffer hits, 15 100 строк Index Scan; keyset — 0,053 мс, 7 shared buffer hits, 100 строк Index Scan. В данном прогоне keyset оказался примерно в 36 раз быстрее. Полный результат — `evidence/explain_history.txt`.
**Проверки отказов.** Использован локальный стенд Docker Compose в WSL. PostgreSQL 17.6, Redis 8.2.2, один API-контейнер. Создавался тестовый пользователь и действующая сессия. Зависимости останавливались по очереди, HTTP-ответы измерялись через `curl %{time_total}`. Выполнено два прогона сценария отказов.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| Штатный перезапуск API, PostgreSQL и Redis | Сохранение данных и действующей сессии | `make test-persistence` — PASS | Потеря подтверждённых данных не обнаружена; время не измерялось |
| Остановка Redis | 503 без анонимного доступа | `/health/ready` и `/users/me` — 503; `/health/live` — 200 | Ответ `/users/me`: 4,006 и 8,000 с; после восстановления прежний токен работает; точное время восстановления не измерялось |
| Остановка PostgreSQL | 503 без необработанной ошибки | `/health/ready` и `/users/me` — 503; `/health/live` — 200 | Ответ `/users/me`: 4,006 и 4,008 с; после восстановления — 200; точное время восстановления не измерялось |
| Истечение TTL | Отказ в доступе | После TTL=2 секунды получен 401 | Сессия становится недействительной |
| Конкурентная регистрация | Уникальность username | Один 201, один 409 | Дублирования username нет |
| Ошибка составной операции | Полный rollback | Частично созданных записей нет | Частичные изменения откатились |
Время обработки отказных запросов оказалось ограниченным в проведённых тестах, но строгая максимальная задержка на уровне сервера не доказана. Отдельный нагрузочный эксперимент с RPS, p50/p95/p99, CPU/RAM, заданной интенсивностью запросов и прогревом не проводился. Поэтому такие метрики не приводятся.
## Ограничения и следующие шаги
Приложение сохраняет данные и действующие сессии после проверенного штатного перезапуска с сохранением volumes. При недоступности PostgreSQL или Redis возвращается 503, после восстановления работа продолжается. Автоматического переключения на резервные экземпляры нет.
Redis AOF с `appendfsync everysec` не гарантирует отсутствие потери последних изменений при аварийном сбое. Удаление volumes приводит к потере локальных данных. Резервное копирование и восстановление в новое хранилище пока не реализованы.
Эффективность keyset-пагинации подтверждена одним экспериментом на 20 000 сообщениях. Результаты не следует переносить на любую нагрузку без дополнительных измерений. Стоимость записи при разных индексах не исследовалась.
В дальнейшем планируется выполнить трек 2 для оценки 5: эксперимент на 100 000+ сообщениях с неравномерным распределением по чатам, сравнение индексов и стоимости вставки, backup и восстановление в новое хранилище с проверкой данных.