Files
2026-10-16 19:53:27 +03:00

217 lines
27 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
- Автор, группа: Никифорова Екатерина, БВТ2301
- Целевая оценка: **5**, выбранный трек 5: **Трек 2 «План запроса и восстановление»** (уровни 3 и 4 тоже выполнены)
- Commit/PR: #64
- Источники, библиотеки и помощь ИИ: FastAPI 0.115 + Uvicorn 0.30 (как в lab1), psycopg 3.2 + psycopg_pool, argon2-cffi, redis-py; документация PostgreSQL (transactions, EXPLAIN), Valkey persistence, RFC 7617.
## Запуск из чистого clone
Требования: Docker Engine ≥ 24 с Compose v2, Python ≥ 3.9 (для тестов), `sh` (Git Bash на Windows).
```sh
sh scripts/init-secrets.sh # случайные пароли -> secrets/*, копия .env.example -> .env (всё в .gitignore)
docker compose --env-file .env config --quiet # проверка конфигурации
docker compose --env-file .env up -d --build # postgres -> migrate (одноразово) -> valkey -> api
until curl -fs localhost:8080/health/ready; do sleep 1; done
python tests/smoke.py --base-url http://localhost:8080 # публичный smoke
cd tests_student && python test_integration.py && python test_dependencies.py && cd .. # расширенные тесты API (11 + зависимости)
python scripts/track2_indexes.py --out evidence/track2-indexes.json # трек 2: замеры индексов
python scripts/track2_restore.py --src-url "$DATABASE_URL" --dst-admin-url "$DST_URL" --out evidence/track2-restore.json
```
Оператору больше ничего делать не нужно. Миграции применяет сервис `migrate` (идемпотентно, под advisory-lock).
Безопасная остановка: `docker compose --env-file .env stop` (данные и тома целы). Намеренное удаление учебных данных:
`docker compose --env-file .env down -v && rm -rf secrets` — **только это стирает тома**; в `restart.sh` и тестах `-v` не используется.
## Архитектура и решения
```
Клиент ──HTTP──> api (FastAPI, Uvicorn) ──> PostgreSQL 17 (источник истины, том pgdata)
└──────────────> Valkey 8 (кэш сессий, AOF, том valkeydata)
migrate (одноразово) ──> PostgreSQL
```
| Роль | Service | Образ (зафиксирован) | Health | Том | Сеть/порт | Credentials |
| --- | --- | --- | --- | --- | --- | --- |
| api | `api` | сборка из `Dockerfile`, база `python:3.11.9-slim` (как в lab1), зависимости из `requirements.txt` | `/health/ready` (API + PostgreSQL) | нет (stateless, read-only rootfs) | `127.0.0.1:8080` | secrets-файлы `database_url`, `cache_url` |
| postgres | `postgres` | `postgres:17.6-alpine` | `pg_isready` | `pgdata` | только внутренняя сеть | `POSTGRES_PASSWORD_FILE` |
| valkey | `valkey` | `valkey/valkey:8.1.3-alpine` | `valkey-cli ping` | `valkeydata` | только внутренняя сеть | `--requirepass` из secrets-файла |
| migrate | `migrate` | образ api | — (завершается) | — | внутренняя | `database_url` |
**Источник истины.** Пользователи, чаты, участники, сообщения и сессии — в PostgreSQL. Valkey хранит только производные данные
(кэш сессий) и может быть потерян без потери данных.
**Схема (`app/migrations/`).** `users` (UNIQUE username + CHECK формата), `chats`, `chat_members` (PK `(chat_id,user_id)`),
`messages` (композитный FK `(chat_id,sender_id) -> chat_members`: в чат пишет только участник — инвариант в БД, а не только в коде),
`sessions` (PK = SHA-256 токена). Индексы: `messages(chat_id, created_at, id)` — история; `chats(created_at,id)`;
`chat_members(user_id, chat_id)`; `sessions(expires_at)`.
**Транзакционные границы.** (1) Регистрация: Argon2id считается *до* транзакции (без удержания соединения), затем один `INSERT`;
гонку одинаковых username решает `UNIQUE` → `409`. (2) Создание чата: проверка участников + `INSERT chats` + `INSERT chat_members`
в одной транзакции; любая ошибка → ROLLBACK. (3) Сообщение: один `INSERT`; COMMIT происходит до ответа `201`.
(4) Логин: проверка пароля → `INSERT sessions` в транзакции → после COMMIT прогрев кэша.
**Сессии и кэш (уровень 4).**
- *Источник истины* — таблица `sessions` (в БД хранится SHA-256 токена, не сам токен). Токен — `secrets.token_urlsafe(32)` (256 бит).
- *Кэш*: cache-aside `sess:v1:<sha256(token)>` → `{user, exp}`. Чтение: Valkey → при промахе PostgreSQL → `SET NX PX`.
- *Expiry*: `expires_at` в PostgreSQL; в кэше TTL = `min(SESSION_CACHE_TTL_SECONDS, остаток жизни)` **и** `exp` проверяется в самой записи — срок не зависит от точности TTL ключа.
TTL не продлевается ни обращениями, ни рестартом.
- *Инвалидация*: logout = `DELETE` в PostgreSQL → после COMMIT `SET sess:v1:… "revoked"` (tombstone, TTL = cache TTL). Заполнение кэша — `SET NX`, поэтому медленный
параллельный читатель не «воскресит» отозванную сессию поверх tombstone. Негативные результаты не кэшируются (защита от забивания кэша мусорными токенами).
Пользователи в этом API неизменяемы, поэтому инвалидации данных пользователя не требуется.
- *Persistence Valkey*: AOF `everysec` + том. Строго она не обязательна (истина в PostgreSQL), но стенд подтверждает рестарт всех хранилищ.
- *Известная граница*: если logout выполнен, пока Valkey недоступен, tombstone не записывается, и после возврата Valkey (AOF сохраняет TTL) отозванная сессия может
ещё ≤ `SESSION_CACHE_TTL_SECONDS` (60 с) приниматься из кэша. Это осознанный компромисс; снижается уменьшением TTL кэша.
**Пул, таймауты, ошибки.** `psycopg_pool`: `max_size=16` на процесс (2 процесса uvicorn = 32 из 100 соединений PostgreSQL), потоков sync-обработчиков 24, ожидание соединения 3 с, `connect_timeout=3`, `statement_timeout=5 s`, `lock_timeout=3 s`,
`idle_in_transaction_session_timeout=10 s`, `check_connection` при выдаче (после рестарта PostgreSQL мёртвые соединения отбрасываются). Valkey: таймаут 0,25 с +
circuit breaker 2 с. Все запросы параметризованы (psycopg передаёт параметры отдельно от SQL; конкатенации SQL нет). Недоступность БД → `503 unavailable`
без деталей; неожиданное исключение → `500 internal_error`, стек — только в серверный лог.
**Критичные зависимости readiness.** PostgreSQL — критична (`/health/ready` = 503 без неё). Valkey — нет (`ready` остаётся 200, кэш обходится).
**Что перенесено из lab1 и что изменено.** Приложение — прямое развитие `main.py` из lab1 (FastAPI/Uvicorn, тот же Dockerfile-подход).
- *Сохранено без изменений по поведению*: маршруты и коды ответов; формат ошибки `{"error":{code,message,request_id}}`; middleware `X-Request-Id` (входящее значение теперь принимается только если оно безопасно: `[A-Za-z0-9._-]{1,64}`, иначе генерируется новое; заголовок есть и в ответах 500/503); keyset-пагинация с курсором, привязанным к ресурсу (`messages`/`chats` + id) и порядком `(created_at, id)`; строгая валидация (лишние поля → 400, неверный Content-Type → 415, пустой/пробельный текст → 400); 404 вместо 403 для чужого чата; `/health/live` и `/health/ready`; `--timeout-graceful-shutdown 5`; тесты lab1 (`tests/test_own.py`, `tests/test_race.py`, 8+1 сценариев) перенесены на Bearer.
- *Изменено (объявленные переходы lab2)*: добавлен `password` при регистрации (Argon2id); `POST /auth/sessions` с Basic; `Authorization: Bearer` вместо `X-User-Id` (заголовок игнорируется); словари под `RLock` заменены PostgreSQL; `threading.RLock` больше не нужен — согласованность обеспечивают транзакции и ограничения БД; `/health/ready` проверяет PostgreSQL.
- *Заменено осознанно*: pydantic-модели lab1 (`extra="forbid"`) заменены строгим разбором JSON (`app/validation.py`): он отвергает дубли ключей, `NaN`, NUL и одиночные суррогаты (после них PostgreSQL возвращал бы 500), а проверка доступа (404) выполняется **до** валидации тела; автодокументация FastAPI (`/docs`) отключена — контракт в `contracts/openapi.json`.
- *Исправлено по сравнению с lab1*: регулярка `^…$` пропускала username с завершающим `\n` (в Python `$` совпадает перед `\n`) — теперь `fullmatch`; `len(display_name)` считался до проверки типов — теперь тип проверяется первым.
**Переменные `.env.example` → код.** `APP_HOST/APP_PORT` — как в lab1, совпадают с `CMD uvicorn main:app --host 0.0.0.0 --port 8080`; число процессов — `WEB_CONCURRENCY` (читает сам uvicorn); `SESSION_TTL_SECONDS` → `app/config.py` (срок сессии);
`DATABASE_URL_FILE`, `CACHE_URL_FILE` → пути к secrets-файлам; `SESSION_STORE` = `postgres` | `postgres+cache`; `SESSION_CACHE_TTL_SECONDS` — TTL записи кэша.
## Доказательства критериев
Основные замеры выполнены в песочнице (без Docker, PostgreSQL 16.15, Redis 7). Дополнительно всё проверено на реальном Docker Compose-стенде
(Windows 11 + Docker Desktop, PostgreSQL 17.6, Valkey 8.1.3):
- `sh scripts/init-secrets.sh` — 4 секрета в `secrets/`, `.env`
- `docker compose --env-file .env up -d --build` — postgres/migrate/valkey/api, api healthy
- `python tests/smoke.py --base-url http://localhost:8080` → PASS
- Persistence: полный рестарт api+valkey+postgres тем же Bearer-токеном → 200 (`evidence/persistence-my.txt`)
- Миграции идемпотентны: `migrate` повторно → «nothing to do» (`evidence/migrations-my.txt`)
- Свои тесты: 11/11 passed (`evidence/tests-my.txt`)
- Тесты зависимостей (`evidence/tests-deps-my.txt`)
- **Трек 2 — индексы (2 прохода)**: `evidence/track2-indexes-my.json`, `evidence/track2-indexes-pass2-my.json`
- **Трек 2 — backup/restore со сверкой md5**: `evidence/track2-restore-my.txt`
(SRC=DST: users 1, chats 563, messages 102000, sessions 1; md5 совпал)
- Теги `postgres:17.6-alpine` и `valkey/valkey:8.1.3-alpine` проверены через `docker pull`
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл |
| --- | --- | --- | --- |
| Тесты lab1 в новой аутентификации + гонка регистрации | `pytest tests/test_own.py tests/test_race.py -v` | 15 passed | `test-results.txt` |
| Публичный smoke | `python tests/smoke.py` | `PASS: lab2 public API scenario` | `test-results.txt`, `smoke_docker.txt` |
| Контракт offline | `python scripts/check_contract.py` | `PASS: offline skeleton structure…` | `test-results.txt` |
| PostgreSQL: таблицы, PK/FK, UNIQUE, миграции с нуля | `python -m app.migrate` ×2 | 1-й запуск: применены 0001, 0002; 2-й: «nothing to do» | `migrations.txt`, `migrations-my.txt` |
| Атомарное создание чата | `tests_student/test_db_rollback.py` | FK-ошибка после `INSERT chats` → 0 строк остаётся | `test-results.txt` |
| Basic только на `/auth/sessions`, Bearer везде, `X-User-Id` игнорируется | smoke + `test_integration.py` | 401 с корректными `WWW-Authenticate` | `test-results.txt` |
| Пароли — KDF | код `app/security.py` | Argon2id (m=19 MiB, t=2, p=1), соль на пароль, rehash при смене параметров | — |
| Рестарт API и хранилищ, сессии живы | `docker compose stop api valkey postgres && up -d` | тот же токен работает после рестарта | `persistence-restart.txt`, `persistence-my.txt` |
| Secrets/volumes не в Git | `.gitignore`, `.dockerignore` | `secrets/`, `.env` исключены; в образ не копируются | — |
| **4:** Valkey реально используется | `evidence/cache-role.txt` | ключи `sess:v1:<sha256>`, PTTL ≤ 60 000 мс; tombstone после logout; сессия переживает `FLUSHALL` | `cache-role.txt` |
| **4:** параметризованные запросы, пул, таймауты | код `app/db.py`, `app/repo.py` | см. «Пул, таймауты» | — |
| **4:** гонка регистрации | `test_integration.py::registration_race_same_username` | 16 параллельных → ровно один 201, 15×409 | `test-results.txt` |
| **4:** индекс истории, EXPLAIN на ≥10 000 | `scripts/explain_history.py` (100 000 строк) | keyset с индексом: Index Scan, 4 буфера, **0,03–0,04 мс**; без индекса: Seq Scan 1235 буферов, **~8–9 мс** | `explain-history.txt` |
| **4:** expiry (короткий TTL) | `tests_student/test_expiry.py 2` | после 3,5 с: 401 на `users/me`, `chats`, `logout` | `test-results.txt` |
| **4:** logout, неверный пароль | smoke + `logout_revokes_only_that_session` | 204; повтор 401; неверный пароль 401 | `test-results.txt` |
| **5 (трек 2):** ≥100 000 сообщений, ≥2 индекса/запроса, цена записи | `scripts/track2_indexes.py` (2 прохода, Windows + Docker) | см. раздел «Трек 5.2» | `track2-indexes*.json`, `track2-indexes-my.json`, `track2-indexes-pass2-my.json` |
| **5 (трек 2):** backup → восстановление → сверка | `docker exec pg_dump/pg_restore` + md5 | counts SRC=DST (users 1, chats 563, messages 102000, sessions 1), md5 совпал | `track2-restore-my.txt` |
| **4:** недоступность Valkey/БД | `tests_student/test_dependencies.py` | Valkey off/flush → 200; PostgreSQL off → `ready`=503; после старта токен целы | `dependency-failure.txt`, `tests-deps-my.txt` |
Пагинация: `pagination_walk_and_cursor_binding` — 250 сообщений от 8 параллельных писателей, обход страницами 100/37, нет потерь/дублей/перестановок; курсор чужого чата → 400.
## Эксперименты и отказы
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| Полный рестарт API + PostgreSQL + Valkey, тома сохранены | сессии и данные целы, прежний токен работает | PASS (`persistence-restart.txt`, `persistence-my.txt`) | потерь нет |
| Остановка Valkey | API работает через PostgreSQL | все запросы 200, `ready` 200, задержка < 2,5 с (circuit breaker) | мгновенно; потерь нет |
| `FLUSHALL` Valkey | сессии берутся из PostgreSQL, кэш наполняется заново | токены работают | мгновенно |
| Остановка PostgreSQL | 503, никакого доверия анониму | `ready`/бизнес 503 (`unavailable`), без токена 401 | после старта БД API восстановился автоматически; потерь нет |
| Короткий TTL (2 с) | сессия перестаёт действовать | 401 после истечения | — |
Методика EXPLAIN: PostgreSQL 16.15 (песочница) и 17.6 (Docker Windows), 100 000 строк (1 чат 20 000 + 4 чата-шума по 20 000), `VACUUM ANALYZE`,
сравнение «без индекса» выполнено удалением индекса в откатываемой транзакции.
## Трек 5.2. План запроса и восстановление
### Гипотезы
- **H1.** Составной индекс `(chat_id, created_at, id)` даёт страницу истории за O(размер страницы) для чата любого размера и любой глубины; индекс только по `chat_id` и «глобальный» `(created_at, id)` — нет.
- **H2.** Дополнительный индекс удорожает запись; цена растёт с шириной индекса (покрывающий `INCLUDE (sender_id, text)` дороже всех).
- **H3.** Логический backup (`pg_dump -Fc`) восстанавливается в новый сервер без потери данных *на момент снапшота*; всё записанное после начала дампа теряется (RPO = возраст бэкапа).
### Методика (повторяемая: `scripts/track2_indexes.py`, `scripts/track2_restore.py`)
- **Данные**: 100 000 сообщений в 563 чатах с неравномерными размерами: 1×50 000, 1×20 000, 1×10 000, 10×1 000, 50×100, 500×10; текст 10–400 символов; плюс 2 000 одиночных вставок в процессе замера записи (итого ≈102 000).
- **Конфигурации** (5): C0 только PK · C1 `(chat_id)` · **C2 `(chat_id, created_at, id)`** · C3 то же `INCLUDE (sender_id, text)` · C4 `(created_at, id)`.
- **Запросы**: Q1 первая страница гиганта (50 000) · Q2 keyset на глубине 40 000 · Q3 первая страница чата из 10 сообщений · Q4 keyset в середине чата из 1 000 · Q5 `OFFSET 40000` (антипример). Страница = 50 (+1) строк.
- **Чтение**: 20 прогревочных + 300 замеров на запрос, p50/p95 клиентской латентности, плюс `EXPLAIN (ANALYZE, BUFFERS)`.
- **Запись**: (а) `INSERT … SELECT` 100 000 строк, 3 повтора, медиана; (б) 2 000 одиночных `INSERT` с коммитом.
- **Повторяемость**: два прохода, второй — в **обратном** порядке конфигураций.
### Результаты — собственные замеры (Windows 11 + Docker Desktop, PostgreSQL 17.6)
**Проход 1** (`evidence/track2-indexes-my.json`):
| Конфигурация | bulk 100k, с | single p50, мс | индекс, МиБ | Q1 p50, мс | Q2 p50, мс | Q3 p50, мс |
| --- | --- | --- | --- | --- | --- | --- |
| C0 (PK only) | 3.00 | 1.770 | 0.0 | 20.143 | 14.824 | 14.878 |
| C1 `(chat_id)` | 3.06 | 1.787 | 0.9 | 14.884 | 14.300 | 0.957 |
| **C2 `(chat_id, created_at, id)`** | 3.11 | 1.733 | 6.9 | **1.219** | **1.196** | **0.932** |
| C3 + `INCLUDE` | 3.79 | 1.741 | 35.6 | 1.184 | 1.221 | 1.050 |
| C4 `(created_at, id)` | 3.26 | 1.904 | 5.0 | 3.453 | 1.492 | 32.912 |
**Проход 2** (`evidence/track2-indexes-pass2-my.json`, обратный порядок):
| Конфигурация | bulk 100k, с | single p50, мс | индекс, МиБ | Q1 p50, мс | Q2 p50, мс | Q3 p50, мс |
| --- | --- | --- | --- | --- | --- | --- |
| C4 | 3.38 | 1.714 | 5.0 | 3.433 | 1.418 | 15.920 |
| C3 | 5.17 | 2.267 | 35.5 | 2.224 | 1.837 | 1.347 |
| **C2** | 3.62 | 1.847 | 6.9 | 1.327 | 1.861 | 1.095 |
| C1 | 3.86 | 2.258 | 0.9 | 17.321 | 16.562 | 1.417 |
| C0 | 3.65 | 1.822 | 0.0 | 18.452 | 18.306 | 14.635 |
### Выводы по гипотезам
- **H1 подтверждена для C2**: 1.2–1.9 мс на любой странице любого чата (от 10 до 50 000 сообщений). C1 деградирует на гиганте (14.9–17.3 мс), C0 — везде 14–20 мс. **C4 хуже всего для маленького чата** (15.9–32.9 мс): планировщик не может эффективно отфильтровать крошечный чат по глобальному порядку.
- **Покрывающий C3 не оправдан**: Q1–Q3 того же порядка, что C2, но индекс **в 5 раз больше** (35.6 МиБ против 6.9 МиБ) и bulk-загрузка дороже (3.79 с и 5.17 с против 3.11 с и 3.62 с у C2).
- **Решение**: оставлен C2 (он же в миграции `0001_core.sql`).
### Backup → восстановление в новое хранилище → сверка (`evidence/track2-restore-my.txt`)
- **Backup**: `docker exec messenger-lab2-postgres-1 pg_dump -U messenger -d messenger -Fc --no-owner -f /tmp/dump.dump` → 3.62 МБ.
- **Новое хранилище**: отдельный контейнер `pg-restore-target` (PostgreSQL 17.6, порт 5434). `docker exec pg_restore --no-owner --exit-on-error` — без ошибок. Затем `ANALYZE`.
- **Сверка** (совпала с источником):
| Таблица | SRC | DST |
| --- | --- | --- |
| users | 1 | 1 |
| chats | 563 | 563 |
| messages | 102000 | 102000 |
| sessions | 1 | 1 |
| md5 всех сообщений | `440f9224c9a3e355f7fbd551e2a078eb` | `440f9224c9a3e355f7fbd551e2a078eb` |
- **Работоспособность копии**: публичный smoke и 11 собственных тестов прошли на API, подключённом к восстановленной БД.
### Время восстановления (RTO) и границы потери данных (RPO)
- **Измерено** (102 тыс. строк, ~65 МиБ): dump ≈0,8 с + restore ≈1,3 с + analyze ≈0,2 с ≈ **2,3 с**. Это **не оценка для продакшена**; на 100× больших данных восстановление займёт минуты.
- **RPO у логического дампа = возраст дампа.** После дампа записано 500 сообщений — в копии их нет (102 000 против 102 500 в источнике). Для сокращения RPO нужны WAL-архивация + `pg_basebackup` (PITR) или синхронная репликация — **в работе не реализованы**.
- **Безопасность при восстановлении**: отозванная после дампа сессия в копии «воскресла». Практика: после восстановления из бэкапа очистить `sessions`.
- **Что не проверялось**: восстановление в другую мажорную версию PostgreSQL, повреждённый дамп, шифрование бэкапа.
### Ограничения методики
- 1 CPU, клиент на той же машине, 2 прохода (не повторы с доверительными интервалами); p95 одиночных вставок шумит.
- Данные синтетические; реальные распределения могут сместить цифры.
- Горячий кэш: все данные поместились в `shared_buffers`/page cache; на «холодном» диске разрыв между Seq Scan и индексом был бы больше.
## Ограничения проверки
- Основные замеры трека 2 сделаны в песочнице Claude (без Docker, PostgreSQL 16.15). **Дополнительно проверено на Windows 11 + Docker Desktop (PostgreSQL 17.6, Valkey 8.1.3)**: init-secrets.sh, docker compose up -d --build, smoke PASS, persistence, миграции, трек 2 (индексы + backup/restore). См. `evidence/*-my.*`.
- Теги образов проверены: `docker pull postgres:17.6-alpine` и `docker pull valkey/valkey:8.1.3-alpine` — оба существуют.
- В evidence использованы PostgreSQL 16 и Redis 7 (песочница) и 17.6/Valkey 8.1.3 (Docker Windows); на проверяемые свойства это не влияет.
- Нагрузочный профиль (`make load`) не снимался — для уровня 4 не требуется.
## Ограничения и следующие шаги
- Выдерживается: рестарт API/PostgreSQL/Valkey с томами; потеря/сброс/недоступность Valkey; кратковременная недоступность PostgreSQL (503 → автоматическое восстановление).
- Не выдерживается: потеря тома PostgreSQL без свежего бэкапа (логический backup делается вручную, расписания и PITR нет); отказ единственного хоста.
- Семантика конкурентных вставок: `created_at` ставится `clock_timestamp()` в момент вставки, а не COMMIT. Для точной гарантии нужна монотонная последовательность (`bigserial`/outbox) — следующий шаг.
- Кэш истории сообщений не делался (трек 1 не заявлен): сейчас кэшируются только сессии.
- HTTP без TLS допустим только для локального стенда с синтетическими данными (Basic — кодирование, а не шифрование).