forked from mtusi2026/mtusi2026lab2
114 lines
24 KiB
Markdown
114 lines
24 KiB
Markdown
# Отчёт — лабораторная 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 сообщений, поведение при отказах. Гипотеза без доказательства: поведение индексов на данных, значительно превышающих память.
|