Files
samsikandCursor ae4d626ce6 Add PostgreSQL storage and Valkey sessions for lab2.
Messages survive restart in Postgres, and bearer sessions persist in Valkey with AOF.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-09 01:21:39 +03:00

9.8 KiB
Raw Permalink Blame History

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

  • Автор, группа: Самсонов Александр, БВТ2303
  • Целевая оценка: 4
  • Commit/PR: TODO после публикации
  • Использованные источники, библиотеки и помощь ИИ: PostgreSQL transactions, PostgreSQL EXPLAIN, Valkey persistence, RFC 7617, hashlib.scrypt, psycopg 3, redis-py. Помощь ИИ в реализации сервера, миграции, Compose и тестов.

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

Нужны Docker Desktop и Python 3.9+ (для публичных тестов; приложение в контейнере — Python 3.12.6).

git clone <url-этого-форка>
cd lb2
Copy-Item .env.example .env
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
docker compose --env-file .env ps

Готовность: GET http://localhost:8080/health/ready возвращает {"status":"ok"}. Миграции применяет сам API при старте, повторный запуск не вставляет данные второй раз: версия записана в schema_migrations.

Проверки:

python tests/smoke.py --base-url http://localhost:8080
python tests/student_level4.py --base-url http://localhost:8080 --deps
docker compose --env-file .env exec -T api python3 /app/explain_history.py

Сохранность после рестарта API, PostgreSQL и Valkey (volumes не удаляются):

# Git Bash или WSL, у scripts/restart.sh должен быть executable bit
chmod +x scripts/restart.sh
python tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://localhost:8080

Короткий TTL сессии:

# в .env: SESSION_TTL_SECONDS=2
docker compose --env-file .env up -d --force-recreate api
python tests/student_level4.py --base-url http://localhost:8080 --expiry
# вернуть SESSION_TTL_SECONDS=3600 и снова up -d --force-recreate api

Остановка без удаления данных:

docker compose --env-file .env stop

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

docker compose --env-file .env down -v

Образы закреплены тегами: python:3.12.6-slim-bookworm, postgres:16.6-bookworm, valkey/valkey:8.0.2. Зависимости Python закреплены в requirements.txt.

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

Клиент --HTTP--> API (src/server.py) --SQL--> PostgreSQL
                      |
                      +--сессия--> Valkey (AOF + volume)

Из lab1 перенесены пользователи, чаты, членство, сообщения, keyset-пагинация, формат ошибок и X-Request-Id. X-User-Id больше не выбирает пользователя. Регистрация требует password. Вход — только POST /api/v1/auth/sessions с Authorization: Basic. Остальные защищённые запросы требуют Authorization: Bearer. Basic на бизнес-запросе даёт 401.

Источник истины

PostgreSQL хранит пользователей, чаты, участников и сообщения. Пароль хранится как scrypt (hashlib.scrypt, параметры N=16384,r=8,p=1), не как SHA-256 и не как plaintext. bcrypt не используется: он обрезает пароль на 72 байтах и не покрывает весь диапазон UTF-8 до 128 code points.

Сессии хранит только Valkey. Ключ — session: + SHA-256 токена, значение — id пользователя, TTL равен SESSION_TTL_SECONDS (по умолчанию 3600). Токен — secrets.token_urlsafe(32), 256 бит, клиенту отдаётся один раз. Сам токен в Redis и в логи не пишется. TTL не продлевается при рестарте: Redis восстанавливает ключ вместе с оставшимся сроком из AOF. Один TTL без диска сессию после рестарта не сохранил бы, поэтому у Valkey включены --appendonly yes --appendfsync everysec и volume valkeydata.

Инвалидация: logout удаляет ключ. Истёкший TTL удаляет ключ сам. Повтор с отозванным токеном — 401.

Транзакционные границы

  • Регистрация: один INSERT. Два параллельных запроса с одним username упираются в UNIQUE; второй получает 409, а не 500.
  • Создание чата: одна транзакция. Сначала вставляется чат, затем проверяются участники и вставляются chat_members. Неизвестный участник поднимает ошибку, транзакция откатывается, чат в списке не появляется.
  • Сообщение: один INSERT ... WHERE EXISTS участника. Чужой чат не создаёт строку и отвечает 404.
  • Сессия не входит в транзакцию PostgreSQL.

Пул: psycopg_pool, максимум 10 соединений, таймаут выдачи 5 с, connect_timeout 3 с, statement_timeout 5 с. Все запросы параметризованы (%s), значения в SQL не подставляются.

История читается так:

SELECT ...
FROM messages
WHERE chat_id = $1
  AND (created_at, id) > ($2, $3)
ORDER BY created_at, id
LIMIT $4

Индекс messages_history_idx (chat_id, created_at, id) позволяет открыть страницу диапазоном, а не сканом всей таблицы. Это проверяет src/explain_history.py на 10000 сообщениях командой EXPLAIN (ANALYZE, BUFFERS).

Готовность и отказ

/health/live проверяет только процесс. /health/ready проверяет PostgreSQL и Valkey: без любого из них ответ 503 unavailable. Запрос без токена при недоступном Valkey остаётся 401, а не успешным анонимным доступом. Запрос с токеном при недоступном Valkey или PostgreSQL — 503, без текста SQL и без токена в ответе.

Соответствие .env.example

Переменная Где используется
APP_HOST, APP_PORT, APP_ENV bind и строка старта API
SESSION_TTL_SECONDS TTL новой сессии в Valkey и expires_at
SESSION_STORE=valkey сессии не пишутся в PostgreSQL
POSTGRES_* контейнер PostgreSQL и сборка DATABASE_URL в Compose
DATABASE_URL API, если нет файла DATABASE_URL_FILE
REDIS_URL API, если нет файла CACHE_URL_FILE

.env в Git не входит. Volumes pgdata и valkeydata тоже.

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

Критерий Команда Что смотреть
Публичный smoke python tests/smoke.py --base-url http://localhost:8080 строка PASS: lab2 public API scenario
Рестарт с тем же токеном python tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://localhost:8080 PASS: persistence preserved confirmed data and existing session
Гонка username, rollback чата, logout, неверный пароль, битый cursor python tests/student_level4.py --base-url http://localhost:8080 ALL STUDENT TESTS PASSED
Недоступность Valkey и PostgreSQL python tests/student_level4.py --base-url http://localhost:8080 --deps PASS dependencies: ready/me дают 503, запрос без токена даёт 401, после старта прежний токен снова 200
Expiry при коротком TTL SESSION_TTL_SECONDS=2, recreate api, python tests/student_level4.py --expiry PASS expiry
План истории docker compose --env-file .env exec -T api python3 /app/explain_history.py в плане Index Scan по messages_history_idx, без Seq Scan
Повтор миграций второй docker compose up в schema_migrations одна строка 001_init.sql, пользователи не задвоены

На этой машине Docker в PATH не найден, поэтому smoke, persistence и EXPLAIN здесь не запускались. Команды выше — то, чем закрываются критерии на стенде.

Ограничения

  • Рестарт выдерживают данные PostgreSQL и ещё не истёкшие сессии Valkey, пока volumes не удалены. down -v стирает и сообщения, и сессии.
  • Потеря Valkey не пускает анонима в API, но и не даёт войти, пока сессии некому хранить: это 503, не обход в PostgreSQL. Отдельной копии сессий в PostgreSQL нет.
  • appendfsync everysec может потерять последнюю секунду записи при жёстком падении процесса Valkey. Обычный docker compose restart делает штатный shutdown, и AOF сбрасывается.
  • Нагрузка больше лабораторного smoke не измерялась.