18 KiB
Отчёт — лабораторная 2
- Автор, группа: Тимаева М.П. БПИ2302
- Целевая оценка; выбранный трек 5, если нужен: 5, трек 1
- 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
python scripts/track1_cache.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 сначала удаляет строку, затем ключ.
Первая страница GET /messages без cursor при limit=50 лежит в ключе history:{chat_id}:{history_version}. Колонка chats.history_version увеличивается в той же транзакции, что и INSERT сообщения, и публикуется в Redis до ответа 201. Чтение, которое начинается после 201, видит новую версию и не читает страницу предыдущей. Гонка «SELECT успел выполниться до commit и записал старую страницу» публикует её только под старой версией. TTL страницы 30 с снимает брошенные ключи и не отвечает за свежесть. Страницы с cursor всегда идут в SQL. Пока один промах выполняет SELECT, остальные запросы того же процесса ждут тот же результат (singleflight на asyncio future). HISTORY_CACHE=naive пишет страницу в ключ без версии и не сбрасывает её при записи; off не кэширует историю. Оба режима только для измерения, обычный docker compose up оставляет protected.
Redis запущен как redis-server --save "" --appendonly no и без своего volume. Рестарт контейнера поднимает пустой кэш. После этого сессия читается из PostgreSQL, а история — тоже из PostgreSQL, пока страница снова не попадёт в кэш.
Таблицы migrations/001_init.sql: users (UNIQUE username), sessions (PK — SHA-256 токена, FK на пользователя, expires_at), chats, chat_members (PK пары, оба FK, position), messages (FK на чат и отправителя), schema_migrations. migrations/002_chat_version.sql добавляет chats.history_version bigint NOT NULL DEFAULT 0. Индекс 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 только кэширует поиск. HISTORY_CACHE по умолчанию protected.
Из 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 |
| Кэш первой страницы истории | python scripts/track1_cache.py, один чат, limit=50, без другой нагрузки на messages |
naive: 8 из 8 чтений после 201 без нового сообщения; 32 холодных GET → 32 скана. off: 20 GET → 20 сканов. protected: 0 из 8 пропусков; 32 GET → 1 скан; 20 тёплых → 0 сканов, p50 5.786 мс против 8.519 мс у холодного промаха. Рестарт Redis: сообщение на месте, сканы 1 затем 0, сессия 200 | evidence/track1.json |
| Повтор миграций не дублирует данные | второй 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. Контракт и публичные тесты не менялись. После трека 1 заново прогнаны smoke (PASS) и persistence (PASS). ID после этого рестарта: api 1538b7d21085, postgres cbe7139645a5, redis c6a09b1c7977. Volume mtusi2026lab2-fork_pgdata на месте. HISTORY_CACHE в контейнере protected, в .env этой переменной нет, SESSION_TTL_SECONDS 3600.
Эксперименты и отказы
Гипотеза трека 1: без версии чата чтение, начатое после уже подтверждённой записи, может получить первую страницу без этого сообщения; версия в ключе убирает такое чтение; singleflight на холодном ключе сводит SELECT истории к одному; тёплая страница не трогает messages и короче холодного промаха.
Методика. Один чат, один и тот же GET /messages?limit=50, стенд без другой нагрузки на messages. Счётчик — дельта idx_scan + seq_scan из pg_stat_user_tables для messages. PostgreSQL публикует эти числа при завершении backend, поэтому скрипт после каждого окна завершает соединения пула и только потом читает статистику. p50 считается по успешным GET на клиенте. В naive процесс держит заполнение страницы 200 мс, чтобы 32 промаха успели открыть свой SELECT; в protected и off этой паузы нет. Скрипт сам переключает HISTORY_CACHE, пересоздаёт только API и в finally возвращает прежний .env.
| Режим | Наблюдение | Сканы messages |
p50, мс |
|---|---|---|---|
| naive, 8 GET, каждый начат после 201 | все 8 без нового сообщения | — | — |
| naive, 32 одновременных GET по холодному ключу | отдельный SELECT на клиента | 32 | 343.766, внутри пауза записи 200 мс |
| off, 20 последовательных GET | кэша нет, каждый GET читает SQL | 20 | 4.950 |
| protected, 8 GET, каждый начат после 201 | новое сообщение есть в каждом | — | — |
| protected, 32 одновременных GET по холодному ключу | один SELECT на всех | 1 | 160.808 |
| protected, холодный промах по одному | страница строится заново | — | 8.519 |
| protected, 20 GET по тёплой странице | таблица messages не читается |
0 | 5.786 |
docker compose restart redis, PostgreSQL жив |
сообщение на месте; первое чтение — промах, второе — попадание; GET /users/me → 200 |
1, затем 0 | — |
Тёплое попадание (5.786 мс) короче холодного промаха (8.519 мс). Один короткий index scan в режиме off дал 4.950 мс: на этом стенде два обращения к Redis близки по времени к одному такому SELECT. Выигрыш тёплой страницы здесь — ноль сканов messages.
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 не удалялся |
docker compose restart redis при живом PostgreSQL |
Подтверждённое сообщение остаётся, первое чтение истории идёт в SQL, следующее берётся из кэша, сессия жива | Сообщение на месте, сканы messages 1 затем 0, сессия 200 |
Кэш после рестарта пуст, потому что RDB и AOF выключены и volume нет. Строки PostgreSQL не пропадали |
Ограничения и следующие шаги
Один процесс API и одна БД. Потеря Docker-хоста уничтожает и API, и PostgreSQL. Redis не хранит сессию сам по себе: после очистки кэша доступна только строка в PostgreSQL, а пока БД недоступна, кэш не принимается за личность. Пул ограничен 10 соединениями и таймаутом 5 с. Идемпотентность и вторая реплика — лабораторная 3 курса.
Singleflight действует внутри одного процесса. Страницы с cursor не кэшируются. Дельта pg_stat_user_tables верна, пока во время окна нет другой нагрузки на messages. TTL 30 с не заменяет версию в ключе. Пауза 200 мс есть только в naive, чтобы одновременные промахи наложились; она входит в p50 этого режима. На этом стенде один index scan короче двух чтений Redis, поэтому тёплый кэш выигрывает числом SQL, а не каждым миллисекундом относительно off.
Учебное упрощение: время сообщения монотонно только внутри одного процесса. Процесс один, поэтому порядок записи и (created_at, id) совпадают.