Implement lab2 PostgreSQL authentication and Redis sessions

This commit is contained in:
ferraronp
2026-10-23 18:33:06 +03:00
parent 65003b6119
commit 5dd32a77ac
23 changed files with 1126 additions and 55 deletions
+126 -20
View File
@@ -1,37 +1,143 @@
# Отчёт — лабораторная 2
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: Авзалов Артур Марсович, БПИ2301
- Целевая оценка: **4** (трек 5 не заявлен)
- Commit/MR: **TODO после публикации**
- Дата локальной проверки: **23 октября 2026 года**, Windows PowerShell + Docker Desktop
- Источники: FastAPI, Pydantic, PostgreSQL/psycopg, Argon2id (argon2-cffi), Redis, Docker Compose. ChatGPT использовался для разработки начальной реализации, тестовых скриптов и документации; студент должен воспроизвести проверки и понимать решения.
> **Статус доказательств (23.10.2026).** На машине студента подтверждены успешная сборка и healthy-статусы API, PostgreSQL, Redis, public smoke после миграции `002`, дополнительные негативные тесты, защита от повреждённой Redis-сессии, persistence при фактическом перезапуске всех трёх сервисов, rollback, SQL EXPLAIN на 10 000 сообщений, TTL=2 и отказ Redis/PostgreSQL. После отказов все три сервиса вновь `healthy`. Все результаты ниже записаны по предоставленному выводу студента, а не по запуску в среде подготовки отчёта. Повторная идемпотентная миграция, non-root runtime и последний smoke после fault injection отдельно ещё не подтверждены.
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Предпосылки: Docker Desktop с Compose v2, Python 3.9+ (для запуска тестов), `make` (либо прямые вызовы `python tests/...`). Все порты внутренних сервисов закрыты с хоста; только API слушает `127.0.0.1:8080`. Синтетические credentials предназначены для изолированного локального стенда, HTTP Basic по сети вне localhost недопустим без TLS.
Windows PowerShell:
```powershell
Copy-Item .env.example .env
# Открой .env локально и поставь случайный пароль без URI-спецсимволов.
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
docker compose --env-file .env ps
python tests/smoke.py
python tests/extra.py
python tests/redis_corruption.py
python tests/resilience.py --mode persistence --action-script scripts/restart.cmd
python tests/dependency.py
# дополнительно:
python scripts/check_contract.py
docker compose --env-file .env run --rm migrate
docker compose --env-file .env exec -T api id
```
Linux/WSL:
```sh
cp .env.example .env
# Установить локальный пароль в .env (не коммитить)
docker compose --env-file .env up -d --build
make check
make test
make test-own
chmod +x scripts/restart.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-dependencies
```
Применение миграций происходит однократным Compose-сервисом `migrate` **до запуска API**. Для отдельной проверки повторного запуска: `docker compose --env-file .env run --rm migrate` (второй запуск не должен ничего изменять). Проверить логи миграций: `docker compose --env-file .env logs migrate`.
Остановка без потери данных: `docker compose --env-file .env down` (без `-v`). Намеренно **полностью удалить** учебные данные: `docker compose --env-file .env down -v` (не запускать при persistence-проверке!). В Git не попадут `.env` и named volumes.
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
```text
Client (localhost:8080) -> FastAPI (1 worker, no mutable business state)
|-> PostgreSQL 16: users, chats, chat_members, messages
`-> Redis 7.4: session:<SHA256(token)> -> user UUID (TTL + AOF)
```
## Доказательства критериев
Образ API: `python:3.12.12-slim-bookworm`, запуск от `app` (non-root); версии зависимостей зафиксированы в `requirements.txt`. PostgreSQL хранит **истину по бизнес-данным**; Redis — **единственное хранилище действующих серверных сессий** (нет локальной памяти процесса). Токен генерируется `secrets.token_urlsafe(32)` (256 бит энтропии); ключ Redis использует SHA-256 от токена, клиенту возвращается только исходное случайное значение. `EX` устанавливает TTL, `DEL` отзывает сессию. AOF с `appendfsync always` сохраняет записи на диск; named volume хранит их при рестарте. TTL при рестарте не продлевается. `FLUSHDB` сотрёт сессии — прежние токены станут недействительными; данные чатов в PostgreSQL сохранятся.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
Пароли хранятся только как Argon2id hash с солью в PostgreSQL (`time_cost=2`, `memory_cost=19456` KiB, `parallelism=1`; библиотека `argon2-cffi`). POST `/api/v1/auth/sessions` принимает только Basic и не использует JSON body; остальные endpoint принимают только `Authorization: Bearer`. Заголовок `X-User-Id` больше не аутентифицирует. Доступ к конкретному чату дополнительно проверяется по `chat_members`; посторонний получает 404. HTTP вне локальной сети не используется.
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
В `db/migrations/001_initial.sql`: PK/FK, UNIQUE(username), UNIQUE(chat_id, user_id), позиция участников и B-tree индекс `idx_messages_chat_history(chat_id, created_at, id)`. Создание чата + участников выполняется в одной транзакции. При ошибке вставок все изменения откатываются; гонка по username отсекается ограничением UNIQUE в PostgreSQL, а не проверкой в памяти Python.
## Эксперименты и отказы
В `db/migrations/002_utf8_binary_strings.sql` пользовательские `display_name`, `chats.title` и `messages.text` конвертируются без потери данных из varchar в `bytea` (сырые UTF-8 байты): PostgreSQL text/varchar не принимает U+0000, хотя семантика API допускает этот символ. Приложение проверяет максимальную длину в **Unicode code points** и UTF-8 валидность до `.encode('utf-8')`; при чтении декодирует bytes. В БД есть ограничение на длину в байтах, а проверка непустого/непробельного значения выполняется на уровне API. Это позволяет хранить `A\u0000B` без 503 и сохранить все существующие записи при миграции.
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
Чтение сообщений — keyset по `(created_at,id)`, без загрузки всей истории в Python, с `LIMIT limit+1`. Последняя запись страницы превращается в cursor; при продолжении проверяется, что запись существует и принадлежит текущему чату. При изменении истории в ходе обхода snapshot между HTTP-запросами не гарантирован. Для составного ключа времени и UUID `id` обеспечивает определённый порядок даже при совпавших метках времени.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
Пул: psycopg_pool, `max_size=DB_POOL_MAX` (по умолчанию 8), ожидание получения соединения — 3 с, время установки БД соединения — 5 с, `statement_timeout` — 5 с, Redis socket/connect timeout — 2 с. При отказе критической БД/Redis — 503, `/health/live` остаётся 200, `/health/ready` становится 503. Неизвестная/отозванная/истёкшая сессия — 401; нельзя обходить недоступный Redis по X-User-Id. API не логирует тела сообщений, токены или пароли.
## Доказательства критериев (фактические прогоны на Windows)
| Критерий | Как проверяли | Наблюдение |
|----------------------------------------|--------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Compose / готовность | `docker compose --env-file .env up -d --build`, `docker compose --env-file .env ps` | API, PostgreSQL и Redis работают и `healthy`; API доступен только на `127.0.0.1:8080` |
| Public smoke после миграции `002` | `python tests/smoke.py` | **PASS**: `lab2 public API scenario; infrastructure and grading evidence remain separate.` |
| Дополнительные негативные тесты | `python tests/extra.py` | **PASS**: login body, пароль из пробелов, проверки JSON, U+0000, лимит входного массива, гонка username и др. |
| Повреждённое значение сессии | `python tests/redis_corruption.py` | **PASS**: испорченная запись отвергается `401` и удаляется |
| Persistence API + PostgreSQL + Redis | `python tests/resilience.py --mode persistence --action-script scripts/restart.cmd` | **PASS**: тот же Bearer-токен, подтверждённые сообщения и данные доступны после restart; hook завершился кодом 0. В отдельном запуске hook показал последовательную остановку API, Redis, PostgreSQL и их запуск без удаления volumes |
| Rollback | `docker compose --env-file .env exec -T api python scripts/rollback_check.py` | **PASS**: вставка чата и участников откатилась целиком после FK-ошибки |
| История 10 000 записей | `docker compose --env-file .env exec -T api python scripts/explain_history.py` | **PASS**: `Index Scan using idx_messages_chat_history`, `rows=50`, `Buffers: shared hit=5`, `Execution Time: 0.377 ms` |
| Session TTL | Временный `SESSION_TTL_SECONDS=2`, `python tests/expiry.py`, затем возвращено `3600` | **PASS**: токен после истечения получает `401`; `printenv` показал `2`, затем `3600` |
| Redis outage | `python tests/dependency.py` | **PASS**: защищённый API и readiness вернули `503`; после восстановления Redis сессия сохранилась |
| PostgreSQL outage | `python tests/dependency.py` | **PASS**: защищённый API и readiness вернули `503`; после восстановления PostgreSQL сессия сохранилась |
| Повторный запуск миграций | `docker compose --env-file .env run --rm migrate` | Миграция `002` применена, затем `Migrations up to date`; **повторный отдельный запуск для идемпотентности — TODO** |
| Non-root непосредственно в контейнере | `docker compose --env-file .env exec -T api id` | **TODO** (Dockerfile задаёт `USER app`, но фактический вывод команды ещё не приложен) |
| Последний smoke после имитации отказов | `python tests/smoke.py` | **TODO** (все контейнеры уже наблюдались `healthy`) |
**Примечание к негативному тесту на 101 участника.** Схема `CreateChat.member_ids` содержит `max_length=100`, поэтому API отклоняет массив длины 101. Текущий `extra.py` использует 100 случайных несуществующих UUID плюс вызывающего, поэтому один этот HTTP-тест не изолирует причину `400`: такое же значение могло бы возникнуть из-за неизвестных пользователей. Это отдельно проверено ревизией схемы; при необходимости добавляется тест со 101 заранее созданным реальным пользователем.
### Короткий TTL (отдельный запуск)
Windows PowerShell **после обычных smoke/persistence**:
```powershell
$env:SESSION_TTL_SECONDS = '2'
docker compose --env-file .env up -d --no-deps --force-recreate api
python tests/expiry.py
Remove-Item Env:SESSION_TTL_SECONDS
docker compose --env-file .env up -d --no-deps --force-recreate api
```
Обоснование: переcоздание только API не удаляет PostgreSQL и Redis volumes. Тест создаёт нового пользователя, токен, спит 3.1 секунды и убеждается, что токен получил 401. После восстановления TTL=3600 повторить smoke. Для PowerShell используйте `python` (в старом skeleton `Makefile` был `python3`).
### SQL EXPLAIN (фактический вывод 23.10.2026)
Отдельная тестовая история: **10 000 сообщений**, chat_id `d94197ba-c1a1-4aa8-af1a-fd67c9138c1e`. `EXPLAIN (ANALYZE, BUFFERS)` для страницы `LIMIT 50` с keyset-условием:
```text
Limit (cost=0.29..5.30 rows=50 width=70) (actual time=0.032..0.067 rows=50 loops=1)
Buffers: shared hit=5
-> Index Scan using idx_messages_chat_history on messages (cost=0.29..501.83 rows=4999 width=70) (actual time=0.030..0.056 rows=50 loops=1)
Index Cond: ((chat_id = 'd94197ba-c1a1-4aa8-af1a-fd67c9138c1e'::uuid) AND (ROW(created_at, id) > ROW('2026-10-23 14:58:41.99321+00'::timestamp with time zone, '8da12be9-184e-42fb-b175-469e45109f3e'::uuid)))
Buffers: shared hit=5
Planning:
Buffers: shared hit=12
Planning Time: 2.458 ms
Execution Time: 0.377 ms
```
Индекс `idx_messages_chat_history(chat_id, created_at, id)` выбран планировщиком. Для конкретного чата применяется условие `(created_at, id) > (cursor_created_at, cursor_id)`; PostgreSQL читает следующую порцию истории по индексу без полного прохода с `OFFSET`. `shared hit=5` означает обращения к страницам, оказавшимся в буферном кэше. `0.377 ms` — время **серверного SQL**, а не end-to-end HTTP latency; не является гарантией под конкурентной нагрузкой или холодным кэшем. Версия PostgreSQL: образ `postgres:16.10-bookworm`; CPU/RAM-профиль хоста в ходе измерения не зафиксирован. Тестовый fixture не очищен автоматически.
## Эксперименты и отказы (23.10.2026)
| Воздействие | Ожидаем | Наблюдали |
|-------------------------------------------|--------------------------------------------------------------|-----------------------------------------------------------------------------|
| Restart API+PG+Redis без удаления volumes | Сохранены пользователи, чаты, сообщения и действующий токен | **PASS**; hook `Exit code: 0`, persistence client подтвердил прежний Bearer |
| Logout | Старый токен далее получает 401 | **PASS** в `tests/extra.py` |
| TTL=2 | Токен после 3.1 с получает 401 | **PASS**, переменная окружения затем восстановлена до 3600 |
| Stop Redis | Readiness и защищённый API 503, после запуска токен работает | **PASS** |
| Stop PostgreSQL | Readiness и защищённый API 503, после запуска токен работает | **PASS** |
| Конкурентная регистрация одного username | 1×201, 9×409 | **PASS** в `tests/extra.py` (assertion на точные количества) |
| Ошибка FK посреди транзакции | Частично созданного чата в БД нет | **PASS**, `rollback_check.py` |
| Повреждение своей записи сессии в Redis | 401, испорченный ключ удалён | **PASS**, `redis_corruption.py` |
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
- Один API процесс (нет LB/реплик, это lab3). PostgreSQL и Redis — single points of failure, HA не заявлен.
- Redis недоступен — защищённые запросы возвращают 503; это корректный fail-closed выбор для сессий. `logout` при отказе Redis **не возвращает 204**: отозвать токен нельзя, API возвращает 503. Положительного кэша поверх PostgreSQL-сессий нет; Redis — единственный источник сессий. Некорректная строка вместо UUID сессии отклоняется 401 с удалением испорченного ключа.
- Нет TLS во внешней сети: тестовый стенд предназначен только для localhost и синтетических паролей.
- Хранение данных гарантируется корректным завершением/рестартом volumes; против отказа диска, утраты volumes или разрушения FS этот стенд не защищает. PostgreSQL durability зависит от fsync/WAL, Redis — от AOF.
- Автоматические сценарии и инъекция отказов сами по себе не доказывают все эксплуатационные свойства. Результаты выше зафиксированы по реальному выводу студента. Осталось отдельно подтвердить `non-root`, идемпотентность повторной миграции и финальный smoke после инъекций отказов.