Files
mtusi2026lab2/REPORT.md
T

114 lines
24 KiB
Markdown
Raw 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
- Автор, группа: Кушнаренко Николай Вячеславович, БПИ2302
- Целевая оценка; выбранный трек 5, если нужен: **5**, трек 2 «План запроса и восстановление»
- Commit/PR: ветка `solution/bpi2302-kushnarenko`; коммит реализации `078c9f5` (`078c9f5f789fe2f4ab994c9ee659c6d4ac37c06a`); PR — https://gitea.privcloud.tech/mtusi2026/mtusi2026lab2/pulls/121
- Использованные источники, библиотеки и помощь ИИ: Python 3.12, uvicorn, asyncpg (PostgreSQL), redis-py (клиент Valkey), argon2-cffi (Argon2id); документация PostgreSQL (EXPLAIN, pg_dump), Valkey. Код lab1 перенесён (HTTP-слой, валидация, формат ошибок, лимиты). Использование ИИ: Codex был использован для помощи с написанием кода, выполнением некоторых заданий, и проверки качества.
## Запуск из чистого clone
Prerequisites: Docker Compose v2, Python ≥ 3.9 (публичные тесты), bash (Git Bash на Windows) для `init-secrets.sh`.
Версии: `python:3.12.12-slim-bookworm@sha256:593bd06e…`, `postgres:17.11-alpine@sha256:b0f9560a…`, `valkey/valkey:8.1.10-alpine@sha256:081c2f5c…`, зависимости — `requirements.txt` (все версии закреплены).
```sh
sh scripts/init-secrets.sh # создаёт secrets/postgres_password и secrets/database_url (в Git не попадают)
cp .env.example .env # необязательные настройки (TTL сессии и т. д.)
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# дождаться готовности (migrate выполняется один раз и завершается, api стартует после него):
curl http://127.0.0.1:8080/health/ready # {"status":"ok"}
python3 tests/smoke.py --base-url http://127.0.0.1:8080 # make test
python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080
```
На Windows (CreateProcess не запускает `.sh`) используйте `scripts/restart.cmd` — тот же `docker compose restart`.
Остановка с сохранением данных: `docker compose --env-file .env stop`. **Намеренное удаление учебных данных**: `docker compose --env-file .env down -v` (удаляет volumes `pgdata` и `valkeydata`).
Миграции: сервис `migrate` (тот же образ, `python -m app.migrate`) выполняется до старта `api`, повторный запуск безопасен (таблица `schema_migrations`, контрольные суммы, advisory lock). Ручной запуск: `docker compose --env-file .env run --rm migrate`.
## Архитектура и решения
```
Клиент ─HTTP─▶ API (uvicorn, 1 процесс) ──asyncpg (пул ≤10)──▶ PostgreSQL 17 [volume pgdata] ← источник истины
└─redis-py (timeout 0.2 c)──▶ Valkey 8 [volume valkeydata] ← кэш сессий
```
| Роль | Сервис compose | Версия/digest | Health/readiness | Volume | Сеть/порт | Credentials |
| -------- | -------------------- | ------------------------------ | ---------------------------------------------------------------- | ------------ | --------------------- | ----------------------------------- |
| api | `api` | собирается из `Dockerfile` | `/health/ready` (HEALTHCHECK), PostgreSQL критичен, Valkey — нет | — | `127.0.0.1:8080` | `DATABASE_URL_FILE` → docker secret |
| postgres | `postgres` | 17.11-alpine@sha256:b0f9560a… | `pg_isready` | `pgdata` | только сеть `backend` | `POSTGRES_PASSWORD_FILE` → secret |
| valkey | `valkey` | 8.1.10-alpine@sha256:081c2f5c… | `valkey-cli ping` | `valkeydata` | только сеть `backend` | без пароля, не опубликован |
| миграции | `migrate` (one-shot) | образ api | завершается кодом 0 | — | `backend` | secret `database_url` |
- **Источник истины** — PostgreSQL: пользователи, чаты, участники, сообщения и сессии. Схема — `migrations/0001_init.sql`: PK/FK, `UNIQUE(username)`, `CHECK`-ограничения, индексы `messages(chat_id, created_at, id)`, `chat_members(user_id, chat_created_at, chat_id)`. Создание чата — одна транзакция (чат + участники); неизвестный участник нарушает FK и откатывает всё.
- **Пароли**: Argon2id (m=19 МиБ, t=2, p=1) в отдельном пуле потоков, не блокируя event loop; для неизвестного username проверяется фиктивный хеш (одинаковые ответ и время).
- **Сессии**: токен — 256 бит (`secrets.token_urlsafe(32)`), в БД и в кэше хранится только SHA-256. TTL — `SESSION_TTL_SECONDS` (по умолчанию 3600), срок считается по часам БД (`now() + интервал`), использование токена срок не продлевает. Logout — `revoked_at` в БД + удаление ключа в Valkey.
- **Роль Valkey** — read-through кэш сессий: ключ `s:<sha256>` → `user_id|expires_ms`, TTL = min(остаток жизни, `SESSION_CACHE_TTL_SECONDS`=60 с). Экономит один SELECT на каждый защищённый запрос. Политика expiry: TTL ключа + проверка `expires_ms`; инвалидация: logout/DEL. При недоступном Valkey кэш обходится (чтение из БД), circuit breaker на 5 с исключает ожидание таймаута; анонимный запрос никогда не считается доверенным. Окно устаревания: если Valkey был недоступен именно во время logout, ключ может прожить ≤ 60 с (после возврата сервиса). Valkey запущен с AOF (`everysec`) и `maxmemory 64mb`, чтобы тёплый кэш переживал рестарт, но корректность от этого не зависит — после потери кэша всё читается из PostgreSQL.
- **Пул соединений и таймауты**: `asyncpg` pool `max_size=10`, ожидание соединения 2 с, `command_timeout=5 с`, `connect timeout=2 с`; все запросы параметризованы (`$1…`), конкатенации SQL нет. Сбои зависимости → `503 unavailable` + `Retry-After`; для чтений один повтор при разорванном соединении пула (после рестарта БД).
- **Readiness**: `/health/ready` = SELECT 1 к PostgreSQL (таймаут 1 с). Недоступность Valkey не останавливает API.
- **История и конкурентные вставки**: `created_at` = `clock_timestamp()` БД (микросекунды), порядок `(created_at, id)`. Две транзакции в одном чате могут зафиксироваться не в порядке `created_at`; читатель, уже прошедший позицию, может не увидеть позднее зафиксированное сообщение с меньшей меткой (snapshot между HTTP-запросами не гарантируется контрактом). Допущение документировано.
- **Лимиты lab1 сохранены**: тело ≤ 64 КиБ (413), `MAX_INFLIGHT` → 429, потолок соединений → 503 JSON.
- Соответствие переменных из `.env.example`: `APP_*`, `SESSION_TTL_SECONDS`, `DATABASE_URL_FILE`, `SESSION_CACHE_TTL_SECONDS`, `DB_POOL_MAX` используются как есть; `VALKEY_URL` задаётся в `compose.yaml`.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Публичный smoke | `python3 tests/smoke.py …` | PASS | `evidence/checks.txt` |
| Persistence: API и ВСЕ хранилища перезапущены, volumes сохранены, прежний токен работает | `tests/resilience.py --mode persistence --action-script scripts/restart.sh` | PASS; `StartedAt` postgres/valkey/api изменился, volumes на месте | `evidence/persistence_containers.txt` |
| Миграции с нуля и повторно без дублирования | `docker compose up` (первый запуск) и `docker compose run --rm migrate` | первый запуск: `migration_applied`, повтор: `applied=0` | `evidence/migrations.txt` |
| Basic только на `POST /auth/sessions`, Bearer на остальных, `X-User-Id` игнорируется, expiry, logout | `student-tests/test_api.py` | 12 тестов OK | `evidence/checks.txt` |
| Пароли хешируются KDF | `test_password_is_not_exposed_or_stored_plain` | в БД `$argon2id$…`, пароль не найден | `evidence/checks.txt` |
| Роль Valkey, TTL, инвалидация, обход при отказе | описание выше + `test_dependencies.py::test_valkey_down_is_bypassed` | API работает без Valkey, logout виден без кэша | `evidence/checks.txt` |
| Параметризованные запросы, пул, таймауты; гонка username; rollback | `test_concurrent_registration_of_same_username`, `test_chat_creation_is_atomic` | из 12 параллельных регистраций — 1×201 и 11×409; после неудачного создания чата числа строк в `chats`/`chat_members` не изменились | `evidence/checks.txt` |
| Индекс истории и EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщений | `research/track2_plans_backup.py` (105 000 сообщений) | keyset-запрос: Index Scan, 6 буферов, 0.07 мс против Seq Scan + Sort, 2 632 буфера, 10 мс без индекса | `evidence/track2_explain_plans.txt` |
| Expiry при коротком TTL | `student-tests/test_expiry.py` (SESSION_TTL_SECONDS=2) | через 3.5 с токен → 401 (кэш и БД), TTL не продлевается использованием | `evidence/checks.txt` |
| Недоступность БД/кэша | `student-tests/test_dependencies.py` | PostgreSQL остановлен → 503 JSON + `Retry-After`, `/health/ready` 503, без токена 401; после старта БД API восстановился сам и сессия действует | `evidence/checks.txt` |
| Нагрузочный профиль | `tests/load.py --duration 20 --concurrency 8` | 0 ошибок, ≈960 успешных RPS (урезан клиентом на urllib), p95 ≈ 16 мс | `evidence/load.json` |
| Трек 2 | `research/track2_plans_backup.py` | см. ниже | `evidence/track2_results.json`, `track2_explain_plans.txt` |
## Эксперименты и отказы (трек 2)
**Гипотеза.** Составной индекс `(chat_id, created_at, id)` превращает страницу истории в чтение ~50 строк по индексу независимо от размера чата и позиции в нём, а цена — рост индекса и небольшое замедление записи. Логический backup `pg_dump -Fc` позволяет восстановить полное состояние в новом хранилище, граница потери данных — момент backup.
**Методика** (`research/track2_plans_backup.py`; PostgreSQL 17.11 в Docker, 1 CPU, `shared_buffers=128MB`; отдельная БД `research`, данные синтетические). Набор: **105 000 сообщений** в 1 106 чатах неравномерного размера (1 × 60 000, 5 × 5 000, 100 × 100, 1 000 × 10), 200 пользователей. 4 варианта индексов × 4 запроса; `EXPLAIN (ANALYZE, BUFFERS)`, медиана 9 прогонов (прогретый кэш). Стоимость записи: bulk `INSERT … SELECT` всех строк в пустую копию и 5 000 одиночных `INSERT` с тем же набором индексов.
| Вариант индексов | keyset, середина большого чата (50 строк) | первая страница, большой чат | OFFSET 30 000 | первая страница, малый чат (10 сообщений) | bulk-вставка 105 000 | размер индексов |
| -------------------------------------------- | ----------------------------------------- | ---------------------------- | ------------- | ----------------------------------------- | -------------------- | --------------- |
| V0: только PK | 10.20 мс (Seq Scan + Sort, 2 632 буфера) | 9.15 мс | 23.9 мс | 5.79 мс | 0.42 с | 4.3 МБ |
| V1: `(chat_id)` | 8.19 мс (Sort) | 8.78 мс | 22.7 мс | 0.063 мс | 0.49 с | 5.2 МБ |
| **V2: `(chat_id, created_at, id)` — выбран** | **0.076 мс (Index Scan, 6 буферов)** | **0.043 мс** | 3.49 мс | 0.070 мс | 0.53 с | 12 МБ |
| V3: V2 + `INCLUDE (sender_id)` | 0.068 мс | 0.042 мс | 3.59 мс | 0.075 мс | 0.50 с | 15 МБ |
Выводы: keyset-запрос на V2 в ≈130 раз быстрее V0 и V1 и читает 6 страниц вместо 2 632; глубокий OFFSET остаётся ≈50× медленнее keyset (нужно пройти 30 000 записей индекса) — поэтому API использует cursor. Стоимость индекса V2: +25 % времени bulk-вставки относительно V0 и +8 МБ на 105 000 строк; одиночные вставки различаются на уровне шума (30–38 мс на 5 000 строк — различие в пределах погрешности одного прогона). `INCLUDE` почти не даёт выигрыша (index-only scan невозможен, т. к. запрос читает `text`) и увеличивает индекс — отвергнут. Для малого чата индекс по `chat_id` достаточен.
**Backup → восстановление в новое хранилище → сверка.** `pg_dump -Fc` БД `research` → отдельный контейнер `postgres:17.11-alpine` с **новым volume** → `pg_restore`:
| Показатель | Результат |
| -------------------------------------------------------------------------------------- | ------------------------------------------ |
| Размер дампа | 7 765 134 байт (7.4 МБ, 105 000 сообщений) |
| Время backup / restore (RTO для этого объёма) | 1.15 с / 0.85 с |
| Строки (users/chats/members) | 200 / 1 106 / 1 106 — совпадают |
| Контрольная сумма всех сообщений (`md5` по `id, chat_id, sender_id, text, created_at`) | совпадает: `105000 105f3be9…` |
| Выборочная страница истории (100 сообщений с позиции 30 000) | md5 совпадает |
| Индексы | восстановлены (`ix_hist`, `messages_pkey`) |
| 25 сообщений, записанных **после** backup | в восстановленной копии отсутствуют |
**Границы.** RPO логического backup — интервал между дампами: всё записанное после него теряется (подтверждено 25 строками). Для меньшего RPO нужен непрерывный архив WAL / PITR — не реализован. RTO на 7 МБ ≈ 1 с — на промышленных объёмах растёт линейно с размером данных и перестройкой индексов; восстановление также требует остановки записи в старое хранилище. Измерения проведены на одном ноутбуке без конкурирующей нагрузки; абсолютные миллисекунды не переносимы, соотношения (Seq Scan/Sort против Index Scan) — переносимы.
### Отказы (уровень 4)
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| ------------------------------------------ | --------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------ |
| Рестарт API, PostgreSQL и Valkey с volumes | прежний токен работает, данные на месте | `tests/resilience.py` PASS | готовность < 90 с; потери нет |
| Остановка Valkey | кэш обходится, API работает | 5 запросов с токеном — 200, быстрее 3 с; login/logout работают | мгновенно; потери нет |
| Остановка PostgreSQL | 503 вместо 500/анонимного доступа | все защищённые запросы и login → 503 + `Retry-After`; `ready`=503; без токена 401 | после запуска БД API восстанавливается сам; потери нет |
| TTL=2 с | токен отвергается после срока | 401 + `WWW-Authenticate: Bearer` | — |
## Ограничения и следующие шаги
- Выдерживается: рестарт всех компонентов с сохранёнными volumes, отказ Valkey, кратковременная потеря PostgreSQL. Не выдерживается: потеря volume `pgdata` (нужен backup), отказ хоста Docker; PostgreSQL одиночный (SPOF), репликации нет.
- Один API-процесс; нет балансировщика и идемпотентности отправки (lab3).
- Окно инвалидации кэша (≤ 60 с) при недоступном Valkey в момент logout; создание сессии не ограничено rate limit (429 в контракте допустим, но не реализован).
- Подтверждено экспериментами: выбор индекса, корректность backup/restore на 105 000 сообщений, поведение при отказах. Гипотеза без доказательства: поведение индексов на данных, значительно превышающих память.