forked from mtusi2026/mtusi2026lab2
165 lines
14 KiB
Markdown
165 lines
14 KiB
Markdown
Отчёт — лабораторная 2
|
||
|
||
- Автор, группа: Унру Денис, БПИ2303
|
||
- Целевая оценка; 3
|
||
(Redis/Valkey как кэш сессий, параметризованные запросы и пул, индекс истории с EXPLAIN на 10 000
|
||
сообщениях, автоматические проверки expiry/logout/гонки/отказа).
|
||
- Commit/PR: TODO после публикации
|
||
- Использованные источники, библиотеки: FastAPI 0.115.6, Uvicorn 0.34.0,
|
||
psycopg2-binary 2.9.10, redis 5.2.1, argon2-cffi 23.1.0; PostgreSQL 16.4, Valkey 7.2.6.
|
||
Все решения проверены запуском стенда. Первичные материалы: см. README курса.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Prerequisites: Docker Engine/Desktop с Compose v2 и доступом к сети для сборки образа.
|
||
Версии зафиксированы: Python 3.12.7-slim (образ `python:3.12.7-slim`), `postgres:16.4`,
|
||
`valkey/valkey:7.2.6`. Никаких хостовых БД/Redis не требуется.
|
||
|
||
```sh
|
||
# 1. Локальные синтетические секреты (файл в .gitignore, в Git не попадает)
|
||
cp .env.example .env
|
||
# заполните как минимум POSTGRES_USER/POSTGRES_PASSWORD/POSTGRES_DB,
|
||
# APP_HOST/APP_PORT/APP_ENV/SESSION_TTL_SECONDS/SESSION_STORE, DB_POOL_MIN/DB_POOL_MAX
|
||
|
||
# 2. Проверка конфигурации и сборка
|
||
docker compose --env-file .env config --quiet
|
||
docker compose --env-file .env up -d --build
|
||
|
||
# 3. Дождаться готовности (миграции применяются автоматически при старте API)
|
||
until curl -fsS http://localhost:8080/health/ready; do sleep 1; done
|
||
|
||
# 4. Проверки
|
||
python scripts/check_contract.py # = make check
|
||
python tests/smoke.py --base-url http://localhost:8080 # = make test
|
||
python tests/resilience.py --mode persistence --action-script scripts/restart.sh \
|
||
--base-url http://localhost:8080 # = make test-persistence
|
||
python tests/load.py --duration 30 --concurrency 4 --output evidence/load.json
|
||
|
||
# 5. Безопасная остановка (volumes сохраняются)
|
||
docker compose --env-file .env stop
|
||
|
||
# 6. Намеренное удаление только учебных данных
|
||
docker compose --env-file .env down -v
|
||
```
|
||
|
||
На Windows хук `scripts/restart.sh` (POSIX) запускается через `scripts/restart.cmd`
|
||
(та же команда `docker compose restart`); проверка сохранности при этом эквивалентна.
|
||
`make` в среде разработки отсутствовал, поэтому в отчёте приведены эквивалентные python-команды.
|
||
|
||
## Архитектура и решения
|
||
|
||
```
|
||
Клиент --HTTP--> API (FastAPI/Uvicorn, python:3.12.7-slim, non-root)
|
||
| psycopg2 pool (bounded, statement_timeout)
|
||
v
|
||
PostgreSQL 16.4 <-- источник истины: users, chats, chat_members,
|
||
(named volume pgdata) messages, sessions, schema_migrations
|
||
^
|
||
| cache-aside (TTL = остаток жизни сессии)
|
||
Valkey 7.2.6 (named volume valkeydata, AOF) <-- кэш сессий
|
||
```
|
||
|
||
- **Источник истины** — PostgreSQL. Пользователи, чаты, членство, сообщения и **сессии**
|
||
хранятся в БД, поэтому данные и действующие сессии переживают рестарт API и хранилищ.
|
||
- **Сессии**: opaque-токен (`secrets.token_urlsafe(32)`, ≥256 бит). В БД пишется только
|
||
SHA-256-фингерпринт токена (сам токен не хранится). Срок жизни задаёт `SESSION_TTL_SECONDS`
|
||
(по умолчанию 3600). Отзыв — `revoked_at` + удаление ключа из кэша.
|
||
- **Пароли**: Argon2id (`argon2-cffi`). Пароль никогда не возвращается в `User`.
|
||
- **Valkey/Redis — кэш, а не источник истины.** При каждом аутентифицированном запросе сначала
|
||
проверяется кэш (`sess:<sha256>`); промах или недоступность кэша → запрос к PostgreSQL.
|
||
TTL кэша равен остатку жизни сессии, инвалидация — при logout/отзыве. Так как истина в БД,
|
||
потеря кэша не приводит к потере данных, а анонимный запрос не принимается доверенным.
|
||
- **Транзакционные границы**: регистрация пользователя и создание сессии — одиночные INSERT;
|
||
создание чата — одна транзакция (проверка существования участников + INSERT чата +
|
||
INSERT участников); отправка сообщения — проверка членства и INSERT в одной транзакции.
|
||
Гонка регистрации одинакового username разрешается уникальным ограничением `users.username`,
|
||
нарушение перехватывается и превращается в `409 conflict`.
|
||
- **Ограничения и валидация**: длина и формат полей проверяются приложением (код-поинты) и
|
||
дублируются CHECK-ограничениями БД; лишние поля и неверные типы → `400`; `additionalProperties:false`
|
||
соблюдается для всех ответов.
|
||
- **Пагинация истории** — keyset по `(created_at, id)` по возрастанию, курсор непрозрачный и
|
||
привязан к ресурсу (`chat_id`/`user_id`); выборка `LIMIT n+1` определяет `next_cursor` без
|
||
полного сканирования истории.
|
||
|
||
### Соответствие `.env.example` реальной конфигурации
|
||
|
||
| `.env.example` | Реальная переменная | Смысл |
|
||
| --- | --- | --- |
|
||
| `APP_HOST` / `APP_PORT` | то же | bind-адрес/порт Uvicorn |
|
||
| `APP_ENV` | то же | метка окружения (лог) |
|
||
| `SESSION_TTL_SECONDS` | то же | TTL сессии, по умолчанию 3600 |
|
||
| `SESSION_STORE` | то же | `postgres` или `postgres+redis` |
|
||
| `DATABASE_URL_FILE` | `DATABASE_URL` **или** `DATABASE_URL_FILE` | DSN PostgreSQL (поддержаны оба способа) |
|
||
| `CACHE_URL_FILE` | `CACHE_URL` **или** `CACHE_URL_FILE` | DSN Valkey/Redis (кэш) |
|
||
| — | `DB_POOL_MIN` / `DB_POOL_MAX` | границы пула соединений |
|
||
|
||
Приложение читает значение напрямую из переменной, а при её отсутствии — из файла,
|
||
указанного в `*_FILE` (совместимо с Docker secrets). Секретов в Git нет: `.env` в `.gitignore`.
|
||
|
||
### Роли инфраструктуры
|
||
|
||
| Роль | service | Образ (пиннинг) | healthcheck | volume | сеть | credentials |
|
||
| --- | --- | --- | --- | --- | --- | --- |
|
||
| api | `api` | сборка из `Dockerfile` (python:3.12.7-slim) | `HEALTHCHECK` + `/health/live` | — | `backend` | env из `.env` |
|
||
| postgres | `postgres` | `postgres:16.4` | `pg_isready` | `pgdata` | `backend` | `POSTGRES_*` из `.env` |
|
||
| cache | `valkey` | `valkey/valkey:7.2.6` | `valkey-cli ping` | `valkeydata` (AOF) | `backend` | `CACHE_URL` из `.env` |
|
||
|
||
Bootstrap: миграции `migrations/*.sql` применяются самим API при старте (таблица
|
||
`schema_migrations`, advisory lock). Повторный запуск не дублирует данные.
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||
| --- | --- | --- | --- |
|
||
| Структура skeleton | `python scripts/check_contract.py` | `PASS: offline skeleton structure...` | `evidence/check.txt` |
|
||
| Публичный smoke | `python tests/smoke.py --base-url http://localhost:8080` | `PASS: lab2 public API scenario` | `evidence/smoke.txt` |
|
||
| Данные и сессия переживают рестарт | `python tests/resilience.py --mode persistence --action-script scripts/restart.sh ...` | `PASS: persistence preserved confirmed data and existing session`; StartedAt всех контейнеров изменился, volumes сохранены | `evidence/persistence.txt` |
|
||
| PostgreSQL = источник истины, ключи, уникальность, миграции с нуля | миграция `migrations/0001_init.sql` + лог старта API | `applied migration 0001_init`; таблицы/индексы создаются на пустом volume | `evidence/persistence.txt` |
|
||
| Атомарное создание чата | код `store.create_chat` + одна транзакция | rollback при неизвестном участнике; гонка username → `409` | `student-tests/test_lab2.py` |
|
||
| Basic только на `POST /auth/sessions`, остальное — Bearer, expiry и отзыв | `student-tests/test_lab2.py` | wrong password `401` (Basic), `X-User-Id` не работает, logout `204`→`401` (Bearer) | `evidence/cache_outage.txt` |
|
||
| Истечение сессии при коротком TTL | `--expiry` c `SESSION_TTL_SECONDS=2` | `PASS: session expired after 2s TTL` | `evidence/expiry_check.txt` |
|
||
| Параметризованные запросы, пул, таймауты (уровень 4) | код `db.py`/`store.py` | пул `ThreadedConnectionPool`, `statement_timeout`, все SQL параметризованы | код |
|
||
| Индекс истории обоснован EXPLAIN на ≥10 000 сообщений (уровень 4) | `student-tests/perf_explain.sql` | `Index Scan using messages_chat_created_id_idx`, 5 буферов, 0.028 ms против Seq Scan 361 буфер, 2.550 ms | `evidence/explain.txt`, `evidence/explain_no_index.txt` |
|
||
| Отказ Redis/БД (уровень 4) | `--cache-check` и `stop postgres` | аутентификация живёт без кэша; `/health/ready` и аутентифицированные запросы → `503 unavailable` при недоступной БД, `/health/live` → `200` | `evidence/cache_outage.txt`, `evidence/dependency_outage.txt` |
|
||
|
||
## Эксперименты и отказы
|
||
|
||
Оборудование: один Docker-host (Windows, Docker Desktop 29.4.3, Linux engine), образы без
|
||
явных CPU/RAM-лимитов. Прогрев не выделялся; данные синтетические.
|
||
|
||
Нагрузка (closed-loop POST сообщений, `tests/load.py`, см. `evidence/load.json`):
|
||
|
||
| Профиль | Длительность | Concurrency | Успешные RPS | Ошибки | p50 | p95 | p99 |
|
||
| --- | --- | --- | --- | --- | --- | --- | --- |
|
||
| 4 воркера | 15 с | 4 | 236.6 | 0 (0.0) | 16.0 ms | 32.0 ms | 47.0 ms |
|
||
|
||
Ограничения измерения: генератор закрытого контура ограничен клиентом и подвержен coordinated
|
||
omission; latency только по успешным запросам; это пропускная способность HTTP-подтверждений, а
|
||
не счётчик COMMIT.
|
||
|
||
План запроса (10 000 сообщений в чате, keyset-страница):
|
||
|
||
| Вариант | План | Buffers | Execution |
|
||
| --- | --- | --- | --- |
|
||
| С индексом | `Index Scan using messages_chat_created_id_idx` | shared hit=5 | 0.028 ms |
|
||
| Без индекса (indexscan off) | `Seq Scan` + `Sort` | shared hit=361 | 2.550 ms |
|
||
|
||
Отказы:
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| `docker compose restart` (api+postgres+valkey, volumes сохранены) | данные и прежний токен доступны | те же чат/сообщение по прежнему токену | рестарт всех контейнеров; потерь нет |
|
||
| Остановка Valkey (кэш) | аутентификация продолжает работать через БД | `/users/me` по прежнему токену → `200` | кэш пересоберётся сам; потерь нет |
|
||
| Остановка PostgreSQL | `/health/ready` деградирует | `/health/ready` → `503 unavailable`, аутентифицированный запрос → `503 unavailable`, `/health/live` → `200` | `200` после старта БД; потерь нет |
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
- Учебное упрощение: один Docker-host; эксперимент **не** даёт отказоустойчивости к потере
|
||
самого host, а единственная БД и отсутствие LB/реплик не делают стенд HA. Redis выбран как
|
||
кэш, а не единственное хранилище сессий, поэтому его потеря безопасна.
|
||
- Durability PostgreSQL определяется настройками по умолчанию образа; отдельно проверялось
|
||
сохранение при рестарте контейнеров с сохранением volume, а не при потере диска.
|
||
- Не реализовано (вне минимума этой лабы): изменение участников/удаление сообщений, rate limiting,
|
||
идемпотентность отправки (`Idempotency-Key`) и `X-Instance-Id` — это переходы lab3+.
|
||
- Уровень 4 подтверждён частично: кэш сессий, пул/таймауты, индекс и отказы проверены; отдельный
|
||
«трек 5» (согласованность кэша или backup/restore) не заявлен и не измерялся. |