24 KiB
Отчёт — лабораторная 2
- Автор, группа: Кушнаренко Николай Вячеславович, БПИ2302
- Целевая оценка; выбранный трек 5, если нужен: 5, трек 2 «План запроса и восстановление»
- Commit/PR: ветка
solution/bpi2302-kushnarenko; коммит реализации078c9f5(078c9f5f789fe2f4ab994c9ee659c6d4ac37c06a); PR — mtusi2026/mtusi2026lab2#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 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. - Пул соединений и таймауты:
asyncpgpoolmax_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 сообщений, поведение при отказах. Гипотеза без доказательства: поведение индексов на данных, значительно превышающих память.