Files
2026-10-29 10:53:32 +03:00

18 KiB
Raw Permalink Blame History

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