forked from mtusi2026/mtusi2026lab2
Messages survive restart in Postgres, and bearer sessions persist in Valkey with AOF. Co-authored-by: Cursor <cursoragent@cursor.com>
139 lines
9.8 KiB
Markdown
139 lines
9.8 KiB
Markdown
# Отчёт — лабораторная 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 не измерялась.
|