Files
mtusi2026lab2-fork/REPORT.md
T
2026-10-26 17:50:20 +03:00

11 KiB
Raw Blame History

Отчёт — лабораторная 2

  • Автор, группа: Тимаева М.П. БПИ2302
  • Целевая оценка; выбранный трек 5, если нужен: 4
  • Commit/PR: TODO после публикации
  • Использованные источники, библиотеки и помощь ИИ: контракт и README этой лабораторной; PostgreSQL transactions и EXPLAIN; RFC 7617; библиотеки fastapi, uvicorn, asyncpg 0.32.0, redis 8.1.0, argon2-cffi 25.1.0. Реализацию помог собрать агент Cursor.

Запуск из чистого clone

Нужны Docker и Docker Compose v2. Образы закреплены: python:3.14.8-slim-bookworm (digest в Dockerfile), postgres:16.10-alpine и redis:7.4.11-alpine.

cp .env.example .env
# В .env замените POSTGRES_PASSWORD на локальный пароль без символов @ : / # ? и пробелов.
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build

API читает DATABASE_URL, который compose собирает из POSTGRES_USER, POSTGRES_PASSWORD и POSTGRES_DB. REDIS_URL compose задаёт как redis://redis:6379/0. Если заданы DATABASE_URL_FILE или CACHE_URL_FILE, они важнее и содержимое файлов не логируется. Миграции из migrations/ применяются при старте API и записываются в schema_migrations; повторный старт их не исполняет заново. Пароль БД лежит только в неотслеживаемом .env. У Redis пароля нет, своего volume тоже нет.

Дождитесь GET http://127.0.0.1:8080/health/ready → 200 {"status":"ok"}. Для smoke и persistence SESSION_TTL_SECONDS не меньше 300; в .env.example стоит 3600.

make check
make test
chmod +x scripts/restart.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
python scripts/check_grade4.py
python scripts/explain_history.py

scripts/restart.sh перезапускает api, postgres и redis, без down -v. На Windows python не может запустить этот файл через CreateProcess (WinError 193). На этой машине публичный harness был выполнен в контейнере docker:28-cli с python3, в сети compose и с Docker socket. Подробности в evidence/grade4.txt.

Остановка без удаления данных: docker compose --env-file .env stop. Намеренное удаление учебного volume: docker compose --env-file .env down -v.

Архитектура и решения

Клиент ходит в один процесс API. Источник истины для пользователей, чатов, сообщений и сессий — PostgreSQL, named volume pgdata. Redis 7.4 — кэш поиска сессии: ключ session:{sha256 токена}, значение — expires_at. Сырой токен и hash пароля в Redis не пишутся. TTL ключа равен остатку до expires_at и чтением не продлевается. Промах или недоступный Redis не заменяют строку PostgreSQL: личность подтверждается только ею. Logout сначала удаляет строку, затем ключ. После рестарта Redis пуст, и тот же токен находится в PostgreSQL, поэтому отдельная persistence Redis не нужна.

Таблицы migrations/001_init.sql: users (UNIQUE username), sessions (PK — SHA-256 токена, FK на пользователя, expires_at), chats, chat_members (PK пары, оба FK, position), messages (FK на чат и отправителя), schema_migrations. Индекс messages_history_idx (chat_id, created_at, id) обслуживает keyset. Запросы параметризованы ($1 в asyncpg). Пул: min_size 1, max_size 10, таймаут подключения и команды 5 с, statement_timeout 5000 мс. Парольный hash в ответы не выбирается. Клиенту отдаётся сырой opaque-токен (secrets.token_urlsafe(32)).

Создание чата — одна транзакция: все member_ids должны существовать, иначе rollback и 400, затем вставка чата и участников. Занятый username — unique violation → 409 без текста SQL. created_at назначает процесс и делает его строго возрастающим, чтобы порядок (created_at, id) совпадал с порядком записи. Рестарт не меняет expires_at.

GET /health/live проверяет только процесс. GET /health/ready делает SELECT 1; без БД ответ 503 unavailable. Та же 503, а не 500 и не личность из кэша, приходит на Bearer, если PostgreSQL недоступен. Запрос без токена остаётся 401 и до Redis, и до БД. Basic принимается только на POST /api/v1/auth/sessions. Остальные маршруты требуют Bearer. X-User-Id не идентифицирует пользователя. Пароли — Argon2id.

Переменные: APP_HOST, APP_PORT, APP_ENV, LOG_LEVEL, SHUTDOWN_TIMEOUT_SECONDS, SESSION_TTL_SECONDS читаются как в .env.example. DATABASE_URL и REDIS_URL задаёт compose; DATABASE_URL_FILE и CACHE_URL_FILE — необязательные замены. SESSION_STORE=postgres означает, что строка сессии живёт в PostgreSQL, а Redis только кэширует поиск.

Из lab1 сохранены пользователи, чаты, членство, сообщения и keyset-пагинация. Идентификация lab1 (X-User-Id) заменена на пароль, Basic и Bearer.

Доказательства критериев

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke python tests/smoke.py --base-url http://127.0.0.1:8080 на образе из Dockerfile PASS: lab2 public API scenario evidence/grade3.txt
Данные и сессия переживают рестарт API, PostgreSQL и Redis tests/resilience.py --mode persistence --action-script scripts/restart.sh PASS. ID не сменились (87a78974fbc8, cbe7139645a5, e271b1f6ea0e), volume mtusi2026lab2-fork_pgdata на месте, у Redis volume нет evidence/grade4.txt
Гонка username, rollback, неверный пароль, logout, короткий TTL, отказ Redis и PostgreSQL python scripts/check_grade4.py Все семь проверок PASS. После скрипта TTL снова 3600 evidence/grade4.txt
Индекс истории python scripts/explain_history.py, 10 000 сообщений в одном чате Index Scan using messages_history_idx, LIMIT 51, Buffers: shared hit=4, Seq Scan нет evidence/explain.txt
Повтор миграций не дублирует данные второй docker compose restart api, затем counts schema_migrations = 1, users = 14, messages = 6 и до, и после evidence/grade3.txt
Атомарное создание чата python scripts/check_grade3.py 400 на неизвестного участника, в chats строки с этим title нет evidence/grade3.txt
Expiry сессии отдельный прогон с SESSION_TTL_SECONDS=2, затем возврат к 3600 тот же токен через 3 с получил 401 evidence/grade3.txt
Недоступная БД docker compose stop postgres, затем start /health/live 200, /health/ready 503 unavailable без SQL evidence/grade3.txt
Секреты вне Git git check-ignore -v .env .gitignore:2:.env —

make check эквивалентен python scripts/check_contract.py и тоже PASS. Контракт и публичные тесты не менялись.

Эксперименты и отказы

Отдельного нагрузочного эксперимента нет. EXPLAIN снят на 10 000 сообщениях одного чата: вторая страница keyset, LIMIT 51, выполнение 0.363 мс, прочитаны 4 страницы буфера.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
scripts/restart.sh перезапускает api, postgres и redis Тот же Bearer читает прежнее сообщение, volume PostgreSQL сохранён, кэш может опустеть PASS persistence; ID трёх контейнеров те же, volume на месте Готовность уложилась в бюджет теста (90 с). Подтверждённые строки не пропали
Остановлен только Redis Действующая сессия читается из PostgreSQL, аноним получает 401 Так и было После start кэш снова доступен. Данные не терялись
Остановлен только postgres Bearer получает 503 без SQL, аноним — 401 Так и было После start ready снова 200. Volume не удалялся

Ограничения и следующие шаги

Один процесс API и одна БД. Потеря Docker-хоста уничтожает и API, и PostgreSQL. Redis не хранит сессию сам по себе: после очистки кэша доступна только строка в PostgreSQL, а пока БД недоступна, кэш не принимается за личность. Пул ограничен 10 соединениями и таймаутом 5 с. Идемпотентность и вторая реплика — лабораторная 3 курса. Оценка 5 (согласованность кэша под гонкой или эксперимент на ≥100 000 сообщений с backup) не делалась.

Учебное упрощение: время сообщения монотонно только внутри одного процесса. Процесс один, поэтому порядок записи и (created_at, id) совпадают.