11 KiB
Отчёт — лабораторная 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) совпадают.