PostgreSQL как источник истины, непрозрачные сессии в Redis с TTL и AOF, миграции под advisory lock, пул и таймауты, проверки гонки/отката/отказов и отчёт с evidence.
159 lines
15 KiB
Markdown
159 lines
15 KiB
Markdown
# Отчёт — лабораторная 2
|
||
|
||
- Автор, группа: Чиняева, БВТ2301
|
||
- Целевая оценка: **4**; трек 5 не заявлен.
|
||
- Commit/PR: заполняется после публикации ветки `solution/BVT2301-Chinyaeva` и открытия MR.
|
||
- Использованные источники, библиотеки и помощь ИИ: официальная документация PostgreSQL
|
||
(транзакции, EXPLAIN, keyset pagination), Redis (AOF/expiry), RFC 7617 (Basic), Flask,
|
||
psycopg 3, redis-py, argon2-cffi, gunicorn. ИИ-ассистент использовался для генерации
|
||
черновика кода, проверки контракта и подготовки отчёта; все команды и результаты ниже
|
||
воспроизведены на локальном стенде.
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Стенд проверялся на Windows 11 + Docker Desktop 29.9.2 (16 logical CPU, ~15.2 GiB
|
||
доступно Docker). Образы закреплены тегами, `latest` не используется:
|
||
|
||
| Роль | Образ/рантайм | Порт/volume |
|
||
| --- | --- | --- |
|
||
| API | `python:3.12.7-slim-bookworm`, gunicorn 23.0.0, Flask 3.1.0 | `8080` (публикуется Docker) |
|
||
| PostgreSQL | `postgres:16.4-alpine` | `5432` внутри сети, `pgdata` |
|
||
| Redis | `redis:7.4.0-alpine`, AOF `everysec` | `6379` внутри сети, `redisdata` |
|
||
|
||
```sh
|
||
git clone <fork-url>
|
||
cd mtusi2026lab2-Chinyaeva
|
||
|
||
# Локальные синтетические credentials; .env находится в .gitignore.
|
||
cp .env.example .env
|
||
|
||
docker compose --env-file .env up -d --build
|
||
# ждать готовности, не только /health/live:
|
||
until curl -fsS http://localhost:8080/health/ready; do sleep 1; done
|
||
|
||
make test BASE_URL=http://localhost:8080
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://localhost:8080
|
||
```
|
||
|
||
На проверочной машине порт 8080 был занят WSL, поэтому локально использовался
|
||
`API_PORT=18080` в `.env`; это единственное отличие от команд выше. `restart.sh`
|
||
предназначен для Linux/macOS, `restart.cmd` — эквивалент для Windows. Оба выполняют
|
||
`docker compose restart` и **не удаляют volumes**.
|
||
|
||
Остановка и намеренное удаление учебных данных:
|
||
|
||
```sh
|
||
docker compose --env-file .env down # остановка, данные сохраняются
|
||
docker compose --env-file .env down -v # ТОЛЬКО осознанный сброс volumes
|
||
rm .env # локальные credentials
|
||
```
|
||
|
||
Секреты не попадают в Git: `.env`, `secrets/`, `*.key`, `*.pem` уже перечислены в
|
||
`.gitignore`; `compose.yaml` получает `DATABASE_URL`/`CACHE_URL` из окружения.
|
||
`postgres` и `redis` не публикуют порты на хост, API общается с ними по внутренней сети.
|
||
|
||
## Архитектура и решения
|
||
|
||
```
|
||
client --HTTP--> api (gunicorn/Flask, 1 process, 8 threads)
|
||
|-- PostgreSQL: users, chats, chat_members, messages (источник истины)
|
||
'-- Redis: session:<sha256(token)> -> {user_id, expires_at}, TTL
|
||
```
|
||
|
||
- **PostgreSQL — источник истины** для пользователей, чатов, членства и сообщений.
|
||
Все запросы параметризованы (`%s`), SQL собирается только из фиксированных фрагментов.
|
||
- **Redis — хранилище активных сессий.** В ключ пишется SHA-256 от bearer-токена, сам
|
||
токен в Redis не хранится. `SESSION_TTL_SECONDS` (по умолчанию 3600) — единственная
|
||
политика продления: TTL не скользит и не продлевается рестартом. Logout удаляет ключ.
|
||
Источник истины для сессий — Redis; для пользователей/сообщений — PostgreSQL. Если
|
||
Redis потеряет данные, пользователи и сообщения останутся, но сессии станут
|
||
недействительными (401). AOF `appendfsync everysec` + `redisdata` переживают
|
||
штатный рестарт; при потере питания возможна потеря до ~1 секунды последних записей.
|
||
- **Миграции** лежат в `migrations/001_init.sql` и применяются при старте API под
|
||
`pg_advisory_lock`; версия фиксируется в `schema_migrations`, повторный запуск
|
||
пропускает уже применённую миграцию и не дублирует данные.
|
||
- **Транзакционные границы.** Создание чата и всех `chat_members` — одна транзакция;
|
||
сбой вставки участника откатывает чат (проверено инъекцией trigger). Регистрация
|
||
опирается на `UNIQUE(username)`; конкурентная гонка даёт один `201`, остальные `409`.
|
||
- **Пул и таймауты.** `psycopg_pool` 1–10 соединений, acquire timeout 3 с;
|
||
`statement_timeout=5s`, `idle_in_transaction_session_timeout=10s`,
|
||
`lock_timeout=3s`; Redis socket/connect timeout 2 с. При недоступности зависимости
|
||
API возвращает ограниченный `503 unavailable`, а не `200`/`401` с анонимным доступом.
|
||
- **Индексы.** `messages(chat_id, created_at, id)` обслуживает keyset-запрос
|
||
`WHERE chat_id=? AND (created_at,id)>(?,?) ORDER BY created_at,id LIMIT ?`.
|
||
`chats(created_at,id)` — порядок списка чатов; `chat_members(user_id,chat_id)` —
|
||
выборка чатов пользователя; `users.username` уникален.
|
||
- **Ошибки и заголовки.** Каждый ответ, включая 204/health/ошибки, содержит
|
||
`X-Request-Id`; тело ошибки — `{"error":{"code","message","request_id"}}` с тем же
|
||
`request_id`. Basic принимается только на `POST /auth/sessions`; бизнес-endpoint
|
||
требуют Bearer. `X-User-Id` игнорируется. Пароли — Argon2id (argon2-cffi), не SHA-256.
|
||
|
||
## Доказательства критериев
|
||
|
||
Все команды выполнялись 2026-11-06 на указанном стенде; файлы лежат в `evidence/`.
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||
| --- | --- | --- | --- |
|
||
| Offline-структура и синтаксис | `python scripts/check_contract.py` (`make check`) | `PASS: offline skeleton structure...` | `evidence/check.txt` |
|
||
| Публичный smoke уровня 3 | `python tests/smoke.py --base-url http://localhost:18080` | `PASS: lab2 public API scenario` | `evidence/smoke.txt` |
|
||
| Все данные и сессия переживают рестарт API+БД+Redis | `python tests/resilience.py --mode persistence --action-script scripts/restart.cmd --base-url http://localhost:18080` | `PASS: persistence preserved confirmed data and existing session`; контейнеры до/после рестарта | `evidence/persistence.txt`, `evidence/containers-before-restart.txt`, `evidence/containers-after-restart.txt` |
|
||
| PostgreSQL: таблицы, PK/FK, уникальность, миграции | `psql`-запросы к `information_schema`/`pg_indexes`/`schema_migrations` | 5 таблиц, 9 индексов, `001_init`; повторный старт не дублирует | `evidence/schema.txt` |
|
||
| Redis/Valkey с TTL и persistence | `redis-cli INFO persistence`, `DBSIZE`, `TTL session:*` | `aof_enabled:1`, `aof_last_write_status:ok`, TTL сессии ~3486 с | `evidence/redis.txt` |
|
||
| Ограниченный пул и SQL-таймауты | `docker compose exec -T api python student-tests/pool_settings.py` | `statement_timeout=5s`, pool 1–10, acquire timeout 3 с | `evidence/pool_settings.txt` |
|
||
| Гонка регистрации username | `python student-tests/race_username.py --workers 8` | ровно один `201`, семь `409`, затем успешный вход | `evidence/race_username.txt` |
|
||
| Откат составной операции | `docker compose exec -T api python student-tests/rollback_chat.py` | после сбоя вставки участника чата нет; следующий чат создаётся | `evidence/rollback_chat.txt` |
|
||
| Индекс истории и EXPLAIN на ≥10 000 сообщений | `docker compose exec -T api python student-tests/explain_history.py` | `Index Scan using messages_chat_created_at_id_idx`, `rows=51`, `shared hit=4`, 0.124 ms | `evidence/explain_history.txt` |
|
||
| Expiry при коротком TTL | API с `SESSION_TTL_SECONDS=10`, `python student-tests/expiry.py --wait 12` | свежая сессия `200`, через 12 с — `401` + Bearer challenge | `evidence/expiry.txt` |
|
||
| Неверный пароль, Basic на бизнес-endpoint, logout | `python student-tests/auth_negative.py` | `401 Basic` / `401 Bearer` / `204`, повторный logout `401` | `evidence/auth_negative.txt` |
|
||
| Недоступность Redis и PostgreSQL | `python student-tests/fault_matrix.py` | в обоих случаях `503 unavailable`; после старта Redis readiness 0.48 с, PostgreSQL 3.01 с; тот же токен снова `200` | `evidence/fault_matrix.txt` |
|
||
| Граничные случаи контракта | локальный edge-сценарий | extra fields/пустое тело/неизвестный участник/чужой cursor/4001 символ — `400`; лимит ровно `limit` даёт `next_cursor=null` | `evidence/edge_cases.txt` |
|
||
| Нагрузочный профиль (не доказательство capacity) | `python tests/load.py --duration 15 --concurrency 4 --output evidence/load.json` | 2599 успешных POST, 0 ошибок, 172.7 RPS, p50 22.96 ms / p95 38.87 ms / p99 44.76 ms | `evidence/load.json`, `evidence/load.txt` |
|
||
|
||
### Комментарии к доказательствам
|
||
|
||
- `explain_history.txt` получен после `ANALYZE` на 10 000 сообщениях в одном чате.
|
||
План — `Index Scan`, а не `Seq Scan`; на страницу читается 51 строка, а не вся история.
|
||
Это подтверждает отсутствие полного скана на каждую страницу.
|
||
- `fault_matrix.txt` отдельно показывает, что при отказе Redis уже выданный bearer-токен
|
||
не превращается в анонимный доступ: запрос возвращает `503`, а после восстановления
|
||
AOF тот же токен снова даёт `200`.
|
||
- `persistence.txt` дополнен `containers-*.txt`: в `after` все три контейнера имеют
|
||
статус `Up` с малым временем работы, то есть hook действительно перезапустил API,
|
||
PostgreSQL и Redis, а не только приложение.
|
||
- `evidence/redis.txt` содержит только хэш ключа сессии (`session:<sha256>`), не токен.
|
||
В отчёте и evidence нет паролей, токенов и приватных ключей.
|
||
|
||
## Эксперименты и отказы
|
||
|
||
Стенд: один Docker host, API + PostgreSQL + Redis в одной Compose-сети; синтетические
|
||
пользователи и сообщения. Это не проверка HA и не production-сертификат.
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| `docker compose restart` (API+PostgreSQL+Redis), volumes сохранены | данные и прежний токен живы | `PASS` persistence; контейнеры перезапущены | данные не потеряны; TTL сессии не продлён рестартом |
|
||
| Остановка Redis | readiness/запросы с Bearer — `503`, не `200` и не доверенный аноним | `503 unavailable` на `/health/ready` и `/users/me` | после `start redis` readiness 0.48 с; тот же токен `200` (AOF) |
|
||
| Остановка PostgreSQL | readiness/запросы — `503` | `503 unavailable` на `/health/ready` и `/users/me` | после `start postgres` readiness 3.01 с; тот же токен `200` |
|
||
| Инъекция ошибки во вставку `chat_members` | чат не должен остаться | API вернул ограниченный `500 internal_error`, строки чата нет | целостность восстановлена откатом транзакции |
|
||
| 8 одновременных регистраций одного username | ровно один пользователь | один `201`, семь `409 conflict` | дубликатов нет |
|
||
|
||
Ограничения измерения нагрузки: `tests/load.py` — closed-loop генератор, клиент и
|
||
сервер на одном хосте; 172.7 RPS отражают HTTP-подтверждения в этом стенде, а не
|
||
предел PostgreSQL. В отчёте нет универсального проходного RPS.
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
- Один API-процесс и один Docker host: отказ хоста, потеря БД или единственного Redis
|
||
не компенсируются. Горизонтальное масштабирование и LB — задача lab3.
|
||
- Redis хранит только сессии; при полной потере AOF активные сессии исчезнут, но
|
||
пользователи, чаты и сообщения в PostgreSQL останутся. Это осознанная граница:
|
||
сессия — не бизнес-данные.
|
||
- AOF `everysec` допускает потерю до ~1 секунды последних сессионных записей при
|
||
аварийном завершении хоста; штатный рестарт проверен. Для production нужен
|
||
отдельный анализ durability/backup.
|
||
- HTTP без TLS допустим только для локального изолированного стенда с синтетическими
|
||
данными; для удалённой демонстрации нужен TLS (lab7).
|
||
- Нет rate limiting, публичного поиска пользователей, WebSocket и UI — они не входят
|
||
в обязательный минимум lab2.
|
||
- Следующий шаг для lab3: ≥2 API-реплики, общий LB, `Idempotency-Key` и `X-Instance-Id`,
|
||
проверка failover и отсутствия дублей.
|