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

15 KiB
Raw Blame History

Отчёт — лабораторная 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.

После клонирования репозитория перейти в его каталог и создать локальную конфигурацию:

cp .env.example .env
mkdir -p secrets
chmod 700 secrets

Создать согласованные файлы секретов:

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.

Сборка и запуск:

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.

Проверка:

docker compose ps -a
curl -i http://localhost:8080/health/ready
make check
make test

Ожидаемый ответ /health/ready — HTTP 200, {"status":"ok"}.

Дополнительные проверки:

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

Собственные тесты:

python tests_student/test_auth.py
python tests_student/test_race.py
./scripts/test_short_ttl.sh
./scripts/test_failures.sh

Откат транзакции проверяется внутри контейнера:

docker compose run --rm --no-deps \
  -e PYTHONPATH=/app \
  -v "$PWD/tests_student:/app/tests_student:ro" \
  api python tests_student/test_rollback.py

Безопасная остановка с сохранением данных:

docker compose down

Намеренное удаление учебных данных вместе с volumes:

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 и восстановление в новое хранилище с проверкой данных.