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

139 lines
9.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 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).
```powershell
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`.
Проверки:
```powershell
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 не удаляются):
```powershell
# 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 сессии:
```powershell
# в .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
```
Остановка без удаления данных:
```powershell
docker compose --env-file .env stop
```
Удаление учебных данных вместе с volumes:
```powershell
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 не подставляются.
История читается так:
```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 не измерялась.