diff --git a/.env.example b/.env.example index 714c8076..c17a0c05 100644 --- a/.env.example +++ b/.env.example @@ -1,11 +1,16 @@ -# Copy to .env for your LOCAL synthetic test environment; never commit .env. -# These are logical interface suggestions; map actual framework names in REPORT.md. -APP_HOST=0.0.0.0 -APP_PORT=8080 -APP_ENV=lab +# Скопируйте в .env и задайте свои значения; .env в Git не коммитится. +# Пароль без символов @ : / ? # — он подставляется в DATABASE_URL. +POSTGRES_USER=messenger +POSTGRES_PASSWORD=change-me +POSTGRES_DB=messenger + +# Время жизни сессии, сек (smoke и тест рестарта: не меньше 300; тест истечения: 2) SESSION_TTL_SECONDS=3600 -# Choose credentials locally. File paths contain no secret values. -DATABASE_URL_FILE=/run/secrets/database_url -# Optional on 3, required use on 4 in lab2; Redis OR Valkey: -SESSION_STORE=postgres -CACHE_URL_FILE=/run/secrets/cache_url +# Максимальное время жизни записи в кэше сессий Redis, сек +SESSION_CACHE_MAX_TTL=60 + +# Соответствие логическим именам из skeleton (см. REPORT.md): +# APP_HOST/APP_PORT -> 0.0.0.0:8080 в Dockerfile +# DATABASE_URL_FILE -> compose собирает DATABASE_URL из POSTGRES_*; поддерживается и *_FILE +# SESSION_STORE -> postgres (источник истины) + redis (кэш) +# CACHE_URL_FILE -> REDIS_URL (или REDIS_URL_FILE) diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..dfdb8b77 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +*.sh text eol=lf diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..b3cdda2c --- /dev/null +++ b/Dockerfile @@ -0,0 +1,21 @@ +FROM python:3.11.9-slim + +WORKDIR /app + +COPY requirements.txt . +RUN pip install --no-cache-dir -r requirements.txt + +COPY app.py schemas.py db.py cache.py ./ +COPY migrations ./migrations + +# непривилегированный пользователь +RUN useradd --create-home --shell /bin/bash appuser +USER appuser + +EXPOSE 8080 + +HEALTHCHECK --interval=10s --timeout=3s --start-period=10s --retries=3 \ + CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8080/health/ready').read()" || exit 1 + +# exec: uvicorn — PID 1, получает SIGTERM и корректно закрывает пул соединений +CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8080"] diff --git a/REPORT.md b/REPORT.md index e42f2b05..fdd44a89 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,216 @@ # Отчёт — лабораторная 2 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- Автор, группа: Казаков Амин, БВТ2303 +- Целевая оценка: 5, трек 2 «План запроса и восстановление» +- Commit/PR: ветка `solution/bvt2303_kazakov`, ссылка на PR — после публикации +- Использованные источники, библиотеки и помощь ИИ: FastAPI, psycopg 3 + psycopg_pool, argon2-cffi, redis-py; документация PostgreSQL (transactions, EXPLAIN), Redis persistence, RFC 7617. Эндпоинты на SQL, кэш сессий, собственные тесты, скрипт EXPLAIN, схема БД, мигратор и скрипт исследования трека 2 писались вместе с ИИ-ассистентом Claude пошагово. Весь код разобран и объясняется на защите. ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +Проверено на: Windows 11, Docker Desktop (Engine 29.8.2, Compose 5.5.1), 12 CPU / 8 GB RAM для Docker; Python 3.14 на хосте для тестов (тестам нужна только стандартная библиотека, скрипту EXPLAIN — `psycopg`). + +Образы: `postgres:17.6-alpine`, `redis:7.4.2-alpine`, API собирается из `python:3.11.9-slim`; версии Python-зависимостей закреплены в `requirements.txt`. + +```sh +# 1. локальные настройки (в Git не попадают); задать свой POSTGRES_PASSWORD +cp .env.example .env + +# 2. сборка и запуск; миграции применяет само API при старте +docker compose --env-file .env config --quiet +docker compose --env-file .env up -d --build + +# 3. дождаться готовности +curl -f http://localhost:8080/health/ready # {"status":"ok"} + +# 4. публичные проверки +make check +make test +make test-persistence ACTION_SCRIPT=scripts/restart.sh +# на Windows без make: +# python tests/smoke.py +# python tests/resilience.py --mode persistence --action-script scripts/restart.cmd + +# 5. собственные проверки уровня 4 (управляют контейнерами через docker compose) +python student-tests/test_auth.py +python student-tests/test_race.py +python student-tests/test_expiry.py +python student-tests/test_outage.py +python student-tests/explain_history.py # pip install "psycopg[binary]" + +# 6. исследование уровня 5, трек 2 (отдельная база track2_lab, рабочая не трогается) +python student-tests/track2_research.py indexes # 160 000 сообщений, 4 варианта индекса, стоимость записи +python student-tests/track2_research.py backup # pg_dump -> новый контейнер + пустой volume -> pg_restore -> сверка +``` + +Остановка с сохранением данных: `docker compose --env-file .env down` (volume `pgdata` остаётся). +Намеренное удаление учебных данных: `docker compose --env-file .env down -v` — удаляет volume с БД безвозвратно. + +Бутстрап БД: отдельных действий оператора нет. При старте API берёт `pg_advisory_xact_lock`, создаёт `schema_migrations` и применяет в одной транзакции все ещё не применённые `migrations/*.sql` по порядку имён. Повторный старт ничего не дублирует. ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab1, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +``` +клиент ──HTTP──> api (FastAPI, uvicorn, :8080) + ├──> postgres:5432 — источник истины: users, chats, chat_members, messages, sessions + └──> redis:6379 — только кэш сессий (TTL), без persistence +``` + +**Из lab1 перенесено:** контракт эндпоинтов, формат ошибок с `X-Request-Id`, keyset-пагинация по `(created_at, id)`, health. **Изменено:** словари в памяти заменены PostgreSQL; `X-User-Id` заменён на Bearer-сессии; регистрация требует пароль; добавлены Redis и миграции. + +**Схема** (`migrations/001_init.sql`): PK у всех таблиц; FK `chat_members → chats/users`, `messages → chats/users`, `sessions → users`; `UNIQUE(username)` и `CHECK` по регулярке и длинам; составной PK `chat_members(chat_id, user_id)` запрещает дубли участников. Индексы: `messages(chat_id, created_at, id)` — история; `chat_members(user_id)` — «мои чаты»; `sessions(user_id)`. + +**Транзакционные границы:** +- Создание чата — одна транзакция: `INSERT chats` + `INSERT chat_members` для всех участников. Неизвестный участник даёт FK violation, вся транзакция откатывается, ответ 400. +- Регистрация — один `INSERT`. Гонку одинаковых username решает `UNIQUE` в PostgreSQL: проигравшие получают `unique_violation` и ответ 409. +- Остальные записи — одиночные `INSERT/UPDATE` в autocommit-блоке пула. 201 возвращается только после COMMIT. + +**Аутентификация:** пароль хешируется Argon2id (`argon2-cffi`, параметры по умолчанию). `POST /auth/sessions` принимает только Basic. Для несуществующего username тоже выполняется проверка против хеша-заглушки, поэтому время ответа и сам 401 одинаковые. Токен — `secrets.token_urlsafe(32)` (256 бит). В БД хранится только `sha256(token)`: по дампу БД токенами воспользоваться нельзя. Сессия: `expires_at = now() + SESSION_TTL_SECONDS`; logout пишет `revoked_at`. Проверка: `revoked_at IS NULL AND expires_at > now()`. Сначала проверяется аутентификация (401), затем членство в чате (404 для чужого). + +**Redis — роль, источник истины, expiry, инвалидация:** +- Источник истины — `sessions` в PostgreSQL. Redis — read-through кэш `session:` → `{user, expires_at}`. +- TTL записи = `min(оставшаяся жизнь сессии, SESSION_CACHE_MAX_TTL=60 с)`, поэтому кэш никогда не продлевает сессию. +- Logout: сначала `revoked_at` в PostgreSQL, затем в Redis пишется надгробие `revoked`. Кэш заполняется через `SET NX`, поэтому параллельный запрос не перезапишет надгробие. +- Redis без persistence (`--save "" --appendonly no`), потому что он не единственное хранилище. После restart или `FLUSHALL` кэш пуст, сессии читаются из PostgreSQL. Отозванные сессии не «воскресают», это проверено тестом. +- Redis недоступен: фоновый поток делает PING раз в 2 с. Пока Redis «лежит», запросы идут сразу в PostgreSQL. `/health/ready` от Redis не зависит. + +**Пул и таймауты:** `psycopg_pool.ConnectionPool(min 1, max 10, timeout=5 с, check_connection)`, `connect_timeout=5`, `statement_timeout=5000 мс`. У Redis `socket_timeout` и `connect_timeout` по 0,3 с. Все SQL-запросы параметризованы (`%s`). В f-строки подставляются только константные фрагменты условий, без пользовательских данных. + +**Readiness:** критичная зависимость одна — PostgreSQL (`SELECT 1` за ≤2 с, иначе 503). Redis не критичен. + +**Переменные `.env.example` → реальная конфигурация:** + +| Логическое имя skeleton | Реализация | +| --- | --- | +| `APP_HOST`, `APP_PORT` | `0.0.0.0:8080` в Dockerfile/compose | +| `SESSION_TTL_SECONDS` | одноимённая переменная, по умолчанию 3600 | +| `DATABASE_URL_FILE` | compose собирает `DATABASE_URL` из `POSTGRES_*` в `.env`; код поддерживает и `DATABASE_URL_FILE` | +| `SESSION_STORE` | postgres (источник истины) + redis (кэш) | +| `CACHE_URL_FILE` | `REDIS_URL` (поддерживается и `REDIS_URL_FILE`) | ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | - -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +| Публичный smoke | `make check`, `make test` | оба PASS | `evidence/smoke.txt` | +| Данные и сессии переживают рестарт API, PostgreSQL и Redis | `tests/resilience.py --mode persistence` с `scripts/restart.cmd`; отдельно `sh scripts/restart.sh` + smoke | PASS: тот же токен читает те же данные; `StartedAt` всех трёх контейнеров изменился, volume `pgdata` не пересоздавался | `evidence/persistence.txt` | +| PK/FK, UNIQUE username, миграции с нуля, повторный запуск без дублей | `migrations/001_init.sql`, `db.run_migrations` | на пустом volume создаются 5 таблиц и `schema_migrations`; повторный старт API ничего не применяет | `migrations/`, `db.py` | +| Атомарное создание чата / rollback | `student-tests/test_race.py` | чат с неизвестным участником → 400; список чатов не изменился; 0 чатов без участников в БД | `evidence/test_race.txt` | +| Basic только на `POST /auth/sessions`, Bearer на остальных, X-User-Id не даёт доступа | smoke + `student-tests/test_auth.py` | Basic/X-User-Id/чужой токен на бизнес-эндпоинте → 401 с `WWW-Authenticate: Bearer` | `evidence/test_auth.txt` | +| Неверный пароль | `test_auth.py` | 401 с `WWW-Authenticate: Basic ...`; для неизвестного пользователя ответ такой же | `evidence/test_auth.txt` | +| Logout | `test_auth.py` | 204 без тела; тот же токен → 401, хотя он был в кэше; повторный logout → 401 | `evidence/test_auth.txt` | +| Expiry при коротком TTL | `student-tests/test_expiry.py` (API перезапускается с `SESSION_TTL_SECONDS=2`) | через 3,5 с тот же токен → 401 | `evidence/test_expiry.txt` | +| Пароли — password KDF | `app.py`: `argon2.PasswordHasher` (Argon2id) | в `users.password_hash` строка `$argon2id$...` | `app.py` | +| Secrets/volumes не в Git | `.gitignore` (`.env`, `backups/`, `volumes/`) | `git status` не показывает `.env` | — | +| Redis для сессий с TTL; источник истины и инвалидация | `test_auth.py` | ключ `session:*` появляется после запроса; после logout — 401; после `FLUSHALL` действующая сессия работает, отозванная остаётся отозванной | `evidence/test_auth.txt`, `cache.py` | +| Гонка регистрации одинакового username | `test_race.py` | 20 параллельных запросов → 201 ×1, 409 ×19 | `evidence/test_race.txt` | +| Параметризованные запросы, ограниченный пул, таймауты | код | `%s`-параметры; пул max 10, timeout 5 с; `statement_timeout` 5 с | `db.py`, `app.py` | +| Индекс истории + EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщений | `student-tests/explain_history.py` | 25 000 сообщений, чат на 15 000. С индексом keyset-страница: Index Scan, 51 буфер, 0,09 мс. Без индекса: Seq Scan + Sort, 334 буфера, 1,95 мс | `evidence/explain-history.txt` | +| Пагинация без полного scan | там же | keyset читает ~51 буфер на любой глубине; OFFSET 10000 при том же индексе читает 10 095 буферов (для сравнения, в API не используется) | `evidence/explain-history.txt` | +| Недоступность Redis | `student-tests/test_outage.py` | `docker compose stop redis`: вход, чтение, запись и logout работают через PostgreSQL; первый запрос до обнаружения отказа ≈4 с, следующие ≈0,03 с; ready = 200 | `evidence/test_outage.txt` | +| Недоступность БД | `test_outage.py` | `docker compose stop postgres`: запись → 503 `unavailable` за ≈5 с; аноним → 401; неизвестный токен → 503, не 200; ready → 503. После `start` тот же токен работает, история цела | `evidence/test_outage.txt` | ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +Стенд: один Docker-хост (Windows 11, Docker Desktop, 12 CPU / 8 GB), все контейнеры без CPU/RAM-лимитов. Исследование уровня 5 — в разделе «Трек 2» ниже. | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| `scripts/restart.sh`: stop api → restart postgres, redis → start api | данные и действующий токен сохраняются | PASS persistence; smoke после рестарта PASS | ~10–15 с до ready; подтверждённых потерь нет | +| `docker compose stop redis` | обход кэша, без отказа клиентам | всё работает через PostgreSQL; ready 200 | первый запрос ≈4 с (DNS/таймаут), далее без задержки; после `start` кэш снова используется через ≤2 с | +| `redis-cli FLUSHALL` | действующие сессии из БД, отозванные остаются отозванными | так и есть | мгновенно; потерь нет | +| `docker compose stop postgres` | ограниченная ошибка 503, без доверия анониму | 503 за ≈5 с, аноним 401, ready 503 | после `start` ≈несколько секунд; неподтверждённая запись (503) не появилась, подтверждённые на месте | +| `SESSION_TTL_SECONDS=2` | истечение сессии без продления кэшем | через 3,5 с → 401 | — | + +Ответы на вопросы защиты: +- **COMMIT** гарантирует атомарность и видимость изменений. Durability при сбое ОС/питания зависит от `fsync=on` и `synchronous_commit=on`: это значения по умолчанию, они не менялись. С `synchronous_commit=off` последние подтверждённые транзакции могут потеряться. +- **Сессии:** источник истины — PostgreSQL. После flush или restart Redis кэш пуст, сессии подтягиваются из БД, отозванные остаются отозванными. +- **Аутентификация vs доступ:** Bearer отвечает на вопрос «кто ты» (иначе 401). Членство в `chat_members` отвечает на вопрос «можно ли тебе в этот чат» (иначе 404, без раскрытия существования). +- **Хеш пароля vs checksum:** Argon2 намеренно медленный и с солью, чтобы перебор паролей был дорогим. sha256 быстрый и подходит для токена: у токена 256 бит случайности, перебирать его бессмысленно, а проверка нужна на каждом запросе. + +## Трек 2 (оценка 5): план запроса и восстановление + +Скрипт: `student-tests/track2_research.py`. Он работает в отдельной базе `track2_lab` того же PostgreSQL 17.6, к рабочей базе приложения не прикасается. Сырые результаты лежат в `evidence/track2-indexes.txt` и `evidence/track2-backup-restore.txt`. + +### Гипотеза + +1. Составной индекс `(chat_id, created_at, id)` даёт **постоянную** стоимость страницы истории (десятки буферов, доли миллисекунды) **независимо от размера чата и глубины страницы**. Любая более простая альтернатива деградирует хотя бы на одном профиле чатов: огромном, среднем или маленьком. +2. Цену за индекс видно в объёме WAL и в размере индекса, а не во времени одиночного INSERT. +3. `pg_dump` + `pg_restore` в новое хранилище возвращают данные бит в бит на момент снимка. Всё, что записано после снимка, теряется (RPO = интервал между бэкапами). + +### Методика + +- **Данные** (генерация повторяемая, `setseed(0.42)`): 160 000 сообщений в 1 055 чатах с сильно неравномерным распределением: + + | вид чата | чатов | сообщений в каждом | всего | + | --- | --- | --- | --- | + | huge | 1 | 60 000 | 60 000 | + | large | 4 | 10 000 | 40 000 | + | medium | 50 | 1 000 | 50 000 | + | small | 1 000 | 10 | 10 000 | + + Длина текста тоже неравномерна (`10 + 1990·random()³`): большинство сообщений короткие, максимум ≈2000 символов, в среднем ≈512. Таблица `messages` — 90,6 MB heap. +- **Варианты индекса** (PK по `id` есть всегда): **A** `(chat_id, created_at, id)` — текущий; **B** `(chat_id)`; **C** `(created_at, id)`; **D** без индекса. +- **Чтение:** запрос приложения `list_messages` (LIMIT 51) на чатах huge / medium / small: первая страница, keyset-страница на 90 % глубины, а для huge ещё и `OFFSET`. `EXPLAIN (ANALYZE, BUFFERS)`, медиана 7 прогонов, тёплый кэш. +- **Запись:** (а) `INSERT … SELECT` на 20 000 строк, разбросанных по всем чатам; (б) 2 000 отдельных `INSERT`, как делает API. Каждая вставка выполняется в транзакции с `ROLLBACK`, чтобы данные не менялись между вариантами. Медиана 3 прогонов; WAL меряется через `pg_current_wal_insert_lsn()`. +- **Восстановление:** `pg_dump -Fc` из compose-контейнера → новый контейнер `postgres:17.6-alpine` с **новым пустым volume** → `pg_restore` → сверка количества строк по всем таблицам, md5 по всем сообщениям, md5 распределения по чатам, списка индексов и 7 конкретных сообщений. После дампа в источник пишется 1 сообщение, чтобы показать границу потери. + +### Результаты: чтение (время, мс / прочитано буферов) + +| страница | A `(chat_id, created_at, id)` | B `(chat_id)` | C `(created_at, id)` | D нет | +| --- | --- | --- | --- | --- | +| huge, первая | **0,084 / 8** | 40,1 / 12 509 (Seq Scan + Sort) | 0,069 / 51 | 29,5 / 14 269 | +| huge, keyset после 54 000-го | **0,073 / 18** | 20,7 / 4 410 (Bitmap + Sort 6 000 строк) | 0,574 / 1 060 | 26,0 / 14 211 | +| huge, `OFFSET 54000` | 105,8 / 11 691 (Seq Scan + Sort) | 116,6 / 12 509 | 100,5 / 13 389 | 97,3 / 14 269 | +| medium (1 000), первая | **0,080 / 15** | 0,875 / 110 | 3,0 / 5 750 | 25,5 / 14 269 | +| medium, keyset после 900-го | **0,069 / 9** | 0,769 / 110 | 7,5 / 2 274 | 26,1 / 14 211 | +| small (10), первая | **0,050 / 5** | 0,114 / 4 | 24,9 / 13 389 (Seq Scan) | 24,6 / 14 269 | +| small, keyset после 9-го | **0,069 / 4** | 0,114 / 4 | 6,4 / 2 276 | 28,6 / 14 181 | + +### Результаты: запись + +| вариант | размер индекса | построение | 20 000 строк одним INSERT | WAL, Б/строка | 2 000 INSERT по одному | WAL, Б/строка | +| --- | --- | --- | --- | --- | --- | --- | +| A | 9,0 MB | 148 мс | 1 055 мс (52,8 мкс/стр.) | 363 | 294 мс (146,8 мкс/стр.) | 364 | +| B | 1,1 MB | 99 мс | 1 209 мс (60,4) | 308 | 301 мс (150,6) | 340 | +| C | 6,2 MB | 115 мс | 1 089 мс (54,4) | 334 | 282 мс (141,0) | 367 | +| D | — | — | 1 098 мс (54,9) | 227 | 277 мс (138,3) | 257 | + +### Результаты: backup и восстановление + +| этап | результат | +| --- | --- | +| `pg_dump -Fc` | 2,89 с, файл 9,0 MB (сжатый формат; индексы хранятся как DDL, а не как данные) | +| старт нового PostgreSQL на пустом volume | 4,66 с до готовности по TCP | +| `pg_restore` (данные + PK/FK + пересборка индексов) | 3,47 с | +| **RTO** (хранилище + restore, без доставки файла) | **≈8,1 с** на 160 000 сообщений | +| сверка: users / chats / chat_members / messages | 200 / 1 055 / 2 110 / 160 000 — совпало | +| md5 всех сообщений и md5 распределения по чатам | совпали | +| 7 выбранных сообщений (5 случайных + 2 последних в huge) | совпали поле в поле | +| индекс истории после restore | есть и используется: тот же Index Scan, 18 буферов | +| сообщение, записанное после дампа | **отсутствует** в восстановленной базе | + +### Выводы + +1. **Гипотеза 1 подтвердилась.** Только вариант A на всех профилях держит 4–18 буферов и < 0,1 мс. Причина: индекс отсортирован так же, как запрос (`chat_id` = …, затем `ORDER BY created_at, id`), поэтому PostgreSQL сразу встаёт на позицию курсора и читает ровно 51 запись. + - **B** `(chat_id)` находит строки чата, но затем должен прочитать и отсортировать **все** сообщения чата. На огромном чате это 6 000–60 000 строк, в 280–480 раз медленнее, чем A. На маленьком чате B почти не хуже A, то есть проблема видна только при неравномерных данных. + - **C** `(created_at, id)` хорош только для огромного чата: его сообщения составляют 37 % таблицы и быстро встречаются при обходе по времени. Для среднего и маленького чата приходится просматривать тысячи чужих сообщений (5 750 буферов), а для маленького планировщик вообще уходит в Seq Scan (24,9 мс). + - **OFFSET** дорог при любом индексе: 54 000 строк всё равно нужно пропустить, и планировщик выбирает Seq Scan + Sort (≈100 мс, ≈12 000 буферов). Поэтому в API используется keyset. +2. **Гипотеза 2 подтвердилась частично.** Индекс A стоит 9 MB (≈10 % от heap) и **+42–60 % WAL на строку** по сравнению с D (364 против 257 Б и 363 против 227 Б). Время вставки на этом объёме различается в пределах шума (±10 %, B оказался медленнее D). Больше времени уходит на FK-проверки, генерацию UUID и сам heap, а 3 повтора не позволяют различить разницу в несколько процентов. Объём WAL — более надёжная метрика: он влияет на репликацию, архивирование и размер бэкапов PITR. +3. **Гипотеза 3 подтвердилась.** Восстановление в новое хранилище совпало по всем контрольным суммам, RTO ≈8 с. Сообщение, подтверждённое (COMMIT) после дампа, потеряно: при бэкапе `pg_dump` раз в N часов теряется до N часов подтверждённых сообщений. Чтобы сократить RPO до секунд, нужен непрерывный архив WAL (`archive_mode` / `pg_basebackup` + PITR) или реплика. + +### Ограничения исследования + +- Один хост, тёплый кэш: все данные помещались в `shared_buffers`. На холодном диске разница между A и Seq Scan будет ещё больше, но это не измерялось. +- Время записи меряется с шумом Docker Desktop (WSL2). Для достоверной разницы в единицы процентов нужно больше повторов и изолированный стенд. +- `created_at` синтетический (равномерный внутри чата + до 1 минуты разброса). Реальная переписка неравномернее по времени. +- RTO измерен на 160 000 сообщений (дамп 9 MB). Время `pg_restore` растёт примерно линейно с объёмом данных плюс пересборка индексов. Для гигабайтов нужен `pg_restore -j` или физический бэкап. +- Дамп не шифруется и лежит рядом с проектом (`backups/` в `.gitignore`). В реальной системе его нужно хранить отдельно от хоста БД. ## Ограничения и следующие шаги -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +- Один экземпляр PostgreSQL на одном хосте: отказ хоста или диска не переживается. Логический бэкап `pg_dump` и восстановление проверены в треке 2, но автоматического расписания бэкапов и PITR нет. +- Если Redis «зависнет», но сохранит данные (сетевой разрыв, а не остановка), logout в этот момент не запишет надгробие. Устаревшая положительная запись кэша тогда проживёт не дольше `SESSION_CACHE_MAX_TTL` = 60 с. При остановке или рестарте Redis (без persistence) такой проблемы нет. +- Первый запрос после внезапной остановки Redis ждёт ≈4 с, пока резолвится имя `redis` (это не покрывает `socket_connect_timeout`). Дальше фоновый PING отключает кэш. +- `created_at` назначает `now()` PostgreSQL (время начала транзакции). При конкурентных вставках сообщение с меньшим `created_at` может закоммититься позже чтения страницы и не попасть в уже пройденный курсор. Повторов при обходе неизменной истории нет. +- Rate limiting, 413/415 не реализованы: они не обязательны для lab2. +- Порт PostgreSQL проброшен только на `127.0.0.1` (для EXPLAIN-скрипта). Пароль БД передаётся переменной окружения из `.env`; docker secrets — задача lab7. diff --git a/app.py b/app.py new file mode 100644 index 00000000..3f208ded --- /dev/null +++ b/app.py @@ -0,0 +1,490 @@ +import base64 +import binascii +import hashlib +import json +import logging +import os +import secrets +import uuid +from contextlib import asynccontextmanager +from datetime import datetime, timezone + +import psycopg +from psycopg import errors +from argon2 import PasswordHasher +from argon2.exceptions import InvalidHashError, VerificationError +from fastapi import Depends, FastAPI, Header, HTTPException, Query, Request, Response +from fastapi.exceptions import RequestValidationError +from fastapi.responses import JSONResponse +from starlette.exceptions import HTTPException as StarletteHTTPException + +import cache +import db +from schemas import ( + User, CreateUser, Session, + Chat, CreateChat, ChatPage, + Message, CreateMessage, MessagePage, +) + +logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s") +log = logging.getLogger("messenger") + +SESSION_TTL_SECONDS = int(os.environ.get("SESSION_TTL_SECONDS", "3600")) + +ph = PasswordHasher() # по умолчанию Argon2id +# Хеш-заглушка: проверяем пароль даже для несуществующего username, +# чтобы по времени ответа нельзя было узнать, есть ли такой пользователь +DUMMY_HASH = ph.hash("dummy-password-for-timing") + +BASIC_CHALLENGE = {"WWW-Authenticate": 'Basic realm="messenger", charset="UTF-8"'} +BEARER_CHALLENGE = {"WWW-Authenticate": 'Bearer realm="messenger"'} + +ERROR_CODES = { + 400: "invalid_request", + 401: "unauthorized", + 404: "not_found", + 409: "conflict", + 413: "payload_too_large", + 415: "unsupported_media_type", + 429: "rate_limited", + 503: "unavailable", +} + + +@asynccontextmanager +async def lifespan(app): + db.pool.open(wait=True, timeout=30) # ждём, пока БД станет доступна + db.run_migrations() + cache.start() # фоновая проверка доступности Redis + yield # тут приложение работает + db.pool.close() # при остановке (SIGTERM) закрываем пул + + +app = FastAPI(lifespan=lifespan) + + +# ---------- Вспомогательные функции ---------- + +def iso(dt: datetime) -> str: + return dt.astimezone(timezone.utc).isoformat().replace("+00:00", "Z") + + +def parse_uuid(value: str, what: str) -> str: + try: + return str(uuid.UUID(value)) + except ValueError: + raise HTTPException(400, f"invalid {what}") + + +def hash_token(token: str) -> str: + return hashlib.sha256(token.encode()).hexdigest() + + +def check_password(password_hash: str, password: str) -> bool: + try: + return ph.verify(password_hash, password) + except (VerificationError, InvalidHashError): + return False + + +def user_from_row(row) -> User: + return User( + id=str(row["id"]), + username=row["username"], + display_name=row["display_name"], + created_at=iso(row["created_at"]), + ) + + +def chat_from_row(row) -> Chat: + return Chat( + id=str(row["id"]), + title=row["title"], + member_ids=[str(m) for m in row["member_ids"]], + created_at=iso(row["created_at"]), + ) + + +def message_from_row(row) -> Message: + return Message( + id=str(row["id"]), + chat_id=str(row["chat_id"]), + sender_id=str(row["sender_id"]), + text=row["text"], + created_at=iso(row["created_at"]), + ) + + +# Курсор = base64(JSON) с последним (created_at, id) и "областью" (какой чат/список). +# Курсор от другого чата не подойдёт -> 400. +def encode_cursor(scope: str, created_at: datetime, item_id) -> str: + raw = json.dumps({"s": scope, "t": iso(created_at), "i": str(item_id)}) + return base64.urlsafe_b64encode(raw.encode()).decode().rstrip("=") + + +def decode_cursor(cursor: str, scope: str) -> tuple[datetime, str]: + try: + padded = cursor + "=" * (-len(cursor) % 4) + data = json.loads(base64.urlsafe_b64decode(padded)) + if data["s"] != scope: + raise ValueError("cursor from another resource") + return datetime.fromisoformat(data["t"]), str(uuid.UUID(data["i"])) + except (ValueError, KeyError, TypeError, binascii.Error): + raise HTTPException(400, "invalid cursor") + + +def is_member(conn, chat_id: str, user_id: str) -> bool: + row = conn.execute( + "SELECT 1 FROM chat_members WHERE chat_id = %s AND user_id = %s", + (chat_id, user_id), + ).fetchone() + return row is not None + + +# ---------- Ошибки и X-Request-Id ---------- + +def error_response(status: int, message: str, request_id: str, headers=None) -> JSONResponse: + if status in ERROR_CODES: + code = ERROR_CODES[status] + elif status < 500: + code = "invalid_request" + else: + code = "internal_error" + return JSONResponse( + status_code=status, + content={"error": {"code": code, "message": message, "request_id": request_id}}, + headers=headers or {}, + ) + + +@app.middleware("http") +async def request_id_middleware(request: Request, call_next): + rid = request.headers.get("X-Request-Id") + if not rid or len(rid) > 128: + rid = str(uuid.uuid4()) + request.state.request_id = rid + try: + response = await call_next(request) + except psycopg.OperationalError: + # БД недоступна / пул исчерпан (PoolTimeout тоже OperationalError) + log.exception("database unavailable") + response = error_response(503, "service temporarily unavailable", rid) + except Exception: + log.exception("unhandled error") + response = error_response(500, "internal error", rid) + response.headers["X-Request-Id"] = rid + return response + + +@app.exception_handler(RequestValidationError) +async def validation_handler(request: Request, exc: RequestValidationError): + return error_response(400, "invalid request", request.state.request_id) + + +@app.exception_handler(StarletteHTTPException) +async def http_exception_handler(request: Request, exc: StarletteHTTPException): + return error_response(exc.status_code, str(exc.detail), request.state.request_id, exc.headers) + + +# ---------- Аутентификация ---------- + +def parse_basic(authorization: str | None) -> tuple[str, str]: + scheme, _, encoded = (authorization or "").partition(" ") + if scheme.lower() != "basic" or not encoded.strip(): + raise HTTPException(401, "unauthorized", BASIC_CHALLENGE) + try: + decoded = base64.b64decode(encoded.strip(), validate=True).decode("utf-8") + except (binascii.Error, UnicodeDecodeError): + raise HTTPException(401, "unauthorized", BASIC_CHALLENGE) + username, sep, password = decoded.partition(":") # двоеточие в пароле допустимо + if not sep: + raise HTTPException(401, "unauthorized", BASIC_CHALLENGE) + return username, password + + +def current_session(authorization: str | None = Header(default=None)) -> dict: + # Принимаем только Bearer; X-User-Id и Basic здесь игнорируются -> 401 + scheme, _, token = (authorization or "").partition(" ") + token = token.strip() + if scheme.lower() != "bearer" or not token: + raise HTTPException(401, "unauthorized", BEARER_CHALLENGE) + token_hash = hash_token(token) + + # 1. Кэш Redis (если доступен) + cached = cache.get_session(token_hash) + if cached == cache.REVOKED: + raise HTTPException(401, "unauthorized", BEARER_CHALLENGE) + if cached is not None: + return {"user": User(**cached["user"]), "token_hash": token_hash} + + # 2. Промах или Redis недоступен -> источник истины PostgreSQL + with db.pool.connection() as conn: + row = conn.execute( + """ + SELECT u.id, u.username, u.display_name, u.created_at, s.expires_at + FROM sessions s + JOIN users u ON u.id = s.user_id + WHERE s.token_hash = %s + AND s.revoked_at IS NULL + AND s.expires_at > now() + """, + (token_hash,), + ).fetchone() + if row is None: + raise HTTPException(401, "unauthorized", BEARER_CHALLENGE) + user = user_from_row(row) + cache.put_session(token_hash, user.model_dump(), row["expires_at"]) + return {"user": user, "token_hash": token_hash} + + +def current_user(session: dict = Depends(current_session)) -> User: + return session["user"] + + +# ---------- Health ---------- + +@app.get("/health/live") +def liveness(): + return {"status": "ok"} + + +@app.get("/health/ready") +def readiness(): + try: + with db.pool.connection(timeout=2) as conn: + conn.execute("SELECT 1") + except Exception: + raise HTTPException(503, "database unavailable") + return {"status": "ok"} + + +# ---------- Пользователи и сессии ---------- + +@app.post("/api/v1/users", status_code=201, response_model=User) +def register_user(payload: CreateUser): + password_hash = ph.hash(payload.password) + try: + with db.pool.connection() as conn: + row = conn.execute( + """ + INSERT INTO users (id, username, display_name, password_hash) + VALUES (%s, %s, %s, %s) + RETURNING id, username, display_name, created_at + """, + (uuid.uuid4(), payload.username, payload.display_name, password_hash), + ).fetchone() + except errors.UniqueViolation: + # Гонку двух одинаковых регистраций разруливает UNIQUE в БД + raise HTTPException(409, "username already taken") + return user_from_row(row) + + +@app.post("/api/v1/auth/sessions", status_code=201, response_model=Session) +def create_session(authorization: str | None = Header(default=None)): + username, password = parse_basic(authorization) + + with db.pool.connection() as conn: + row = conn.execute( + """ + SELECT id, username, display_name, created_at, password_hash + FROM users WHERE username = %s + """, + (username,), + ).fetchone() + + # Проверка пароля вне соединения с БД: argon2 медленный, не держим соединение пула + if row is None: + check_password(DUMMY_HASH, password) + raise HTTPException(401, "invalid credentials", BASIC_CHALLENGE) + if not check_password(row["password_hash"], password): + raise HTTPException(401, "invalid credentials", BASIC_CHALLENGE) + + token = secrets.token_urlsafe(32) # 32 случайных байта = 256 бит + with db.pool.connection() as conn: + session = conn.execute( + """ + INSERT INTO sessions (token_hash, user_id, expires_at) + VALUES (%s, %s, now() + %s * interval '1 second') + RETURNING expires_at + """, + (hash_token(token), row["id"], SESSION_TTL_SECONDS), + ).fetchone() + + user = user_from_row(row) + # Сессия уже сохранена в PostgreSQL (COMMIT); кэш — только ускорение + cache.put_session(hash_token(token), user.model_dump(), session["expires_at"]) + return Session( + token=token, + token_type="Bearer", + expires_at=iso(session["expires_at"]), + user=user, + ) + + +@app.delete("/api/v1/auth/sessions/current", status_code=204) +def delete_session(session: dict = Depends(current_session)): + with db.pool.connection() as conn: + conn.execute( + "UPDATE sessions SET revoked_at = now() WHERE token_hash = %s AND revoked_at IS NULL", + (session["token_hash"],), + ) + # Сначала отзыв в источнике истины, потом "надгробие" в кэше + cache.revoke_session(session["token_hash"]) + return Response(status_code=204) + + +@app.get("/api/v1/users/me", response_model=User) +def get_me(me: User = Depends(current_user)): + return me + + +# ---------- Чаты ---------- + +@app.post("/api/v1/chats", status_code=201, response_model=Chat) +def create_chat(payload: CreateChat, me: User = Depends(current_user)): + member_ids = [parse_uuid(m, "member id") for m in payload.member_ids] + if len(set(member_ids)) != len(member_ids): + raise HTTPException(400, "member_ids must be unique") + if me.id not in member_ids: + raise HTTPException(400, "caller must be a member") + + chat_id = uuid.uuid4() + try: + with db.pool.connection() as conn: + # Атомарно: чат и все участники сохраняются вместе или не сохраняется ничего + with conn.transaction(): + chat = conn.execute( + "INSERT INTO chats (id, title) VALUES (%s, %s) RETURNING id, title, created_at", + (chat_id, payload.title), + ).fetchone() + with conn.cursor() as cur: + cur.executemany( + "INSERT INTO chat_members (chat_id, user_id) VALUES (%s, %s)", + [(chat_id, m) for m in member_ids], + ) + except errors.ForeignKeyViolation: + # Неизвестный участник: транзакция откатилась, чата в БД нет + raise HTTPException(400, "unknown member") + + return Chat( + id=str(chat["id"]), + title=chat["title"], + member_ids=member_ids, + created_at=iso(chat["created_at"]), + ) + + +@app.get("/api/v1/chats", response_model=ChatPage) +def list_chats( + limit: int = Query(default=50, ge=1, le=100), + cursor: str | None = Query(default=None, min_length=1), + me: User = Depends(current_user), +): + scope = "chats:" + me.id + params: list = [me.id] + after = "" + if cursor is not None: + created_at, last_id = decode_cursor(cursor, scope) + after = "AND (c.created_at, c.id) > (%s, %s)" + params += [created_at, last_id] + params.append(limit + 1) # берём на 1 больше, чтобы понять, есть ли следующая страница + + with db.pool.connection() as conn: + rows = conn.execute( + f""" + SELECT c.id, c.title, c.created_at, + array_agg(m.user_id ORDER BY m.user_id) AS member_ids + FROM chat_members my + JOIN chats c ON c.id = my.chat_id + JOIN chat_members m ON m.chat_id = c.id + WHERE my.user_id = %s {after} + GROUP BY c.id + ORDER BY c.created_at, c.id + LIMIT %s + """, + params, + ).fetchall() + + next_cursor = None + if len(rows) > limit: + rows = rows[:limit] + next_cursor = encode_cursor(scope, rows[-1]["created_at"], rows[-1]["id"]) + return ChatPage(items=[chat_from_row(r) for r in rows], next_cursor=next_cursor) + + +@app.get("/api/v1/chats/{chat_id}", response_model=Chat) +def get_chat(chat_id: str, me: User = Depends(current_user)): + cid = parse_uuid(chat_id, "chat id") + with db.pool.connection() as conn: + if not is_member(conn, cid, me.id): + raise HTTPException(404, "chat not found") # чужой чат = как будто его нет + row = conn.execute( + """ + SELECT c.id, c.title, c.created_at, + array_agg(m.user_id ORDER BY m.user_id) AS member_ids + FROM chats c + JOIN chat_members m ON m.chat_id = c.id + WHERE c.id = %s + GROUP BY c.id + """, + (cid,), + ).fetchone() + return chat_from_row(row) + + +# ---------- Сообщения ---------- + +@app.post("/api/v1/chats/{chat_id}/messages", status_code=201, response_model=Message) +def create_message(chat_id: str, payload: CreateMessage, me: User = Depends(current_user)): + cid = parse_uuid(chat_id, "chat id") + with db.pool.connection() as conn: + if not is_member(conn, cid, me.id): + raise HTTPException(404, "chat not found") + row = conn.execute( + """ + INSERT INTO messages (id, chat_id, sender_id, text) + VALUES (%s, %s, %s, %s) + RETURNING id, chat_id, sender_id, text, created_at + """, + (uuid.uuid4(), cid, me.id, payload.text), + ).fetchone() + return message_from_row(row) + + +@app.get("/api/v1/chats/{chat_id}/messages", response_model=MessagePage) +def list_messages( + chat_id: str, + limit: int = Query(default=50, ge=1, le=100), + cursor: str | None = Query(default=None, min_length=1), + me: User = Depends(current_user), +): + cid = parse_uuid(chat_id, "chat id") + scope = "messages:" + cid + params: list = [cid] + after = "" + if cursor is not None: + created_at, last_id = decode_cursor(cursor, scope) + # keyset-пагинация: продолжаем строго после последнего (created_at, id) + after = "AND (created_at, id) > (%s, %s)" + params += [created_at, last_id] + params.append(limit + 1) + + with db.pool.connection() as conn: + if not is_member(conn, cid, me.id): + raise HTTPException(404, "chat not found") + rows = conn.execute( + f""" + SELECT id, chat_id, sender_id, text, created_at + FROM messages + WHERE chat_id = %s {after} + ORDER BY created_at, id + LIMIT %s + """, + params, + ).fetchall() + + next_cursor = None + if len(rows) > limit: + rows = rows[:limit] + next_cursor = encode_cursor(scope, rows[-1]["created_at"], rows[-1]["id"]) + return MessagePage(items=[message_from_row(r) for r in rows], next_cursor=next_cursor) diff --git a/cache.py b/cache.py new file mode 100644 index 00000000..0f077674 --- /dev/null +++ b/cache.py @@ -0,0 +1,122 @@ +"""Кэш сессий в Redis. + +Источник истины для сессий — PostgreSQL (таблица sessions). Redis только ускоряет +проверку Bearer-токена, чтобы не ходить в БД на каждый запрос. + +Политика: +- ключ session:; значение — JSON {user, expires_at}; +- TTL записи = min(оставшаяся жизнь сессии, SESSION_CACHE_MAX_TTL), поэтому кэш + никогда не продлевает сессию и устаревшая запись живёт не дольше SESSION_CACHE_MAX_TTL; +- logout: сначала revoked_at в PostgreSQL, затем в Redis пишется "надгробие" revoked + (SET без NX), а заполнение кэша идёт через SET NX — параллельный запрос не может + перезаписать надгробие старым "живым" значением; +- Redis недоступен: запрос идёт напрямую в PostgreSQL (обход кэша). Фоновый поток + раз в PROBE_INTERVAL секунд делает PING; пока Redis "лежит", запросы его не трогают + и не тратят время на таймауты/DNS. +""" +import json +import logging +import os +import threading +import time +from datetime import datetime, timezone + +import redis + +from db import read_setting + +log = logging.getLogger("messenger.cache") + +REDIS_URL = read_setting("REDIS_URL") +CACHE_MAX_TTL = int(os.environ.get("SESSION_CACHE_MAX_TTL", "60")) +PROBE_INTERVAL = 2.0 +REVOKED = "revoked" + +_client = ( + redis.Redis.from_url( + REDIS_URL, + socket_timeout=0.3, + socket_connect_timeout=0.3, + decode_responses=True, + ) + if REDIS_URL + else None +) +_healthy = False # до первого успешного PING кэш не используется + + +def _key(token_hash: str) -> str: + return "session:" + token_hash + + +def _available() -> bool: + return _client is not None and _healthy + + +def _mark_down(exc: Exception) -> None: + global _healthy + if _healthy: + log.warning("redis unavailable, bypassing session cache: %s", type(exc).__name__) + _healthy = False + + +def _probe_loop() -> None: + global _healthy + while True: + try: + _client.ping() + if not _healthy: + log.info("redis available, session cache enabled") + _healthy = True + except redis.RedisError as exc: + _mark_down(exc) + except Exception as exc: # например, ошибка DNS, пока контейнер redis остановлен + _mark_down(exc) + time.sleep(PROBE_INTERVAL) + + +def start() -> None: + if _client is not None: + threading.Thread(target=_probe_loop, name="redis-probe", daemon=True).start() + + +def get_session(token_hash: str): + """dict {user, expires_at} | REVOKED | None (промах или Redis недоступен).""" + if not _available(): + return None + try: + raw = _client.get(_key(token_hash)) + except redis.RedisError as exc: + _mark_down(exc) + return None + if raw is None: + return None + if raw == REVOKED: + return REVOKED + data = json.loads(raw) + if datetime.fromisoformat(data["expires_at"]) <= datetime.now(timezone.utc): + return None # страховка: истёкшую запись не используем + return data + + +def put_session(token_hash: str, user: dict, expires_at: datetime) -> None: + if not _available(): + return + remaining = int((expires_at - datetime.now(timezone.utc)).total_seconds()) + ttl = min(remaining, CACHE_MAX_TTL) + if ttl <= 0: + return + value = json.dumps({"user": user, "expires_at": expires_at.isoformat()}) + try: + _client.set(_key(token_hash), value, ex=ttl, nx=True) + except redis.RedisError as exc: + _mark_down(exc) + + +def revoke_session(token_hash: str) -> None: + if not _available(): + return + try: + _client.set(_key(token_hash), REVOKED, ex=CACHE_MAX_TTL) + except redis.RedisError as exc: + _mark_down(exc) diff --git a/compose.example.yaml b/compose.example.yaml index 52524b0c..0d766eda 100644 --- a/compose.example.yaml +++ b/compose.example.yaml @@ -7,4 +7,3 @@ x-required-roles: - postgres # TODO: implement real images/builds, network wiring, volumes, healthchecks, # credentials and bootstrap. Details: contracts/infrastructure.json and README.md. -services: {} diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 00000000..f0d0b975 --- /dev/null +++ b/compose.yaml @@ -0,0 +1,51 @@ +services: + postgres: + image: postgres:17.6-alpine + environment: + POSTGRES_USER: ${POSTGRES_USER} + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} + POSTGRES_DB: ${POSTGRES_DB} + ports: + - "127.0.0.1:5432:5432" # только localhost: для EXPLAIN/исследования, не наружу + volumes: + - pgdata:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"] + interval: 5s + timeout: 3s + retries: 10 + restart: unless-stopped + + # Кэш сессий. Источник истины — PostgreSQL, поэтому persistence Redis не нужна: + # после рестарта/flush кэш пуст, сессии читаются из БД и снова кэшируются. + redis: + image: redis:7.4.2-alpine + command: ["redis-server", "--save", "", "--appendonly", "no", + "--maxmemory", "64mb", "--maxmemory-policy", "allkeys-lru"] + healthcheck: + test: ["CMD", "redis-cli", "ping"] + interval: 5s + timeout: 3s + retries: 10 + restart: unless-stopped + + api: + build: . + image: kazakov-messenger:lab2 + ports: + - "8080:8080" + environment: + DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB} + REDIS_URL: redis://redis:6379/0 + SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600} + SESSION_CACHE_MAX_TTL: ${SESSION_CACHE_MAX_TTL:-60} + depends_on: + postgres: + condition: service_healthy + redis: + condition: service_healthy + stop_grace_period: 10s + restart: unless-stopped + +volumes: + pgdata: diff --git a/db.py b/db.py new file mode 100644 index 00000000..0bf8c6aa --- /dev/null +++ b/db.py @@ -0,0 +1,66 @@ +import os +from pathlib import Path + +from psycopg.rows import dict_row +from psycopg_pool import ConnectionPool + + +def read_setting(name: str, default: str | None = None) -> str | None: + # NAME_FILE (путь к docker secret) имеет приоритет над NAME + path = os.environ.get(name + "_FILE") + if path: + return Path(path).read_text(encoding="utf-8").strip() + return os.environ.get(name, default) + + +DATABASE_URL = read_setting("DATABASE_URL") +if not DATABASE_URL: + raise RuntimeError("DATABASE_URL or DATABASE_URL_FILE must be set") + +# Ограниченный пул соединений: не больше 10 одновременно, ждать свободное не дольше 5 сек +pool = ConnectionPool( + conninfo=DATABASE_URL, + min_size=1, + max_size=int(os.environ.get("DB_POOL_MAX", "10")), + timeout=5, + open=False, + # Перед выдачей соединения проверяем, что оно живо (важно после рестарта БД) + check=ConnectionPool.check_connection, + kwargs={ + "row_factory": dict_row, # строки как dict: row["id"] + "connect_timeout": 5, # таймаут подключения к БД, сек + "options": "-c statement_timeout=5000", # любой SQL-запрос не дольше 5 сек + }, +) + +MIGRATIONS_DIR = Path(__file__).parent / "migrations" +MIGRATION_LOCK_ID = 2026_02 # произвольный номер advisory lock для миграций + + +def run_migrations(): + with pool.connection() as conn: + # Всё в одной транзакции: либо применяются все новые миграции, либо ни одна + with conn.transaction(): + # Если стартуют несколько реплик API, миграции применяет только одна, остальные ждут + conn.execute("SELECT pg_advisory_xact_lock(%s)", (MIGRATION_LOCK_ID,)) + # Таблица, где записано, какие миграции уже применены + conn.execute(""" + CREATE TABLE IF NOT EXISTS schema_migrations ( + version TEXT PRIMARY KEY, + applied_at TIMESTAMPTZ NOT NULL DEFAULT now() + ) + """) + + for file in sorted(MIGRATIONS_DIR.glob("*.sql")): + version = file.name + already = conn.execute( + "SELECT 1 FROM schema_migrations WHERE version = %s", (version,) + ).fetchone() + if already: + continue # уже применена: пропускаем + + conn.execute(file.read_text(encoding="utf-8")) + conn.execute( + "INSERT INTO schema_migrations (version) VALUES (%s)", (version,) + ) + print(f"applied migration {version}", flush=True) diff --git a/evidence/explain-history.txt b/evidence/explain-history.txt new file mode 100644 index 00000000..afbd413d --- /dev/null +++ b/evidence/explain-history.txt @@ -0,0 +1,94 @@ +# EXPLAIN (ANALYZE, BUFFERS) истории сообщений +# всего сообщений: 25000; в исследуемом чате: 15000 +# keyset-курсор указывает на 10 000-е сообщение чата (глубокая страница) + +## С индексом messages_chat_created_idx (chat_id, created_at, id) + +### 1. Первая страница +SELECT id, chat_id, sender_id, text, created_at +FROM messages +WHERE chat_id = %(chat)s +ORDER BY created_at, id +LIMIT 51 + +Limit (cost=0.29..7.67 rows=51 width=78) (actual time=0.016..0.055 rows=51 loops=1) + Buffers: shared hit=54 + -> Index Scan using messages_chat_created_idx on messages (cost=0.29..2170.70 rows=15000 width=78) (actual time=0.016..0.052 rows=51 loops=1) + Index Cond: (chat_id = '9a29690f-123d-4123-9ca9-41776e552bc7'::uuid) + Buffers: shared hit=54 +Planning Time: 0.040 ms +Execution Time: 0.078 ms + +### 2. Глубокая страница, keyset (как в приложении) +SELECT id, chat_id, sender_id, text, created_at +FROM messages +WHERE chat_id = %(chat)s AND (created_at, id) > (%(t)s, %(i)s) +ORDER BY created_at, id +LIMIT 51 + +Limit (cost=0.29..16.94 rows=51 width=78) (actual time=0.023..0.066 rows=51 loops=1) + Buffers: shared hit=51 + -> Index Scan using messages_chat_created_idx on messages (cost=0.29..1627.91 rows=4986 width=78) (actual time=0.023..0.062 rows=51 loops=1) + Index Cond: ((chat_id = '9a29690f-123d-4123-9ca9-41776e552bc7'::uuid) AND (ROW(created_at, id) > ROW('2026-01-21 01:57:43.327018+00'::timestamp with time zone, '42bea608-77e6-48e1-b1ab-68d0c66a93a1'::uuid))) + Buffers: shared hit=51 +Planning Time: 0.073 ms +Execution Time: 0.086 ms + +### 3. Глубокая страница через OFFSET 10000 (для сравнения) +SELECT id, chat_id, sender_id, text, created_at +FROM messages +WHERE chat_id = %(chat)s +ORDER BY created_at, id +OFFSET 10000 LIMIT 51 + +Limit (cost=1447.23..1454.61 rows=51 width=78) (actual time=3.272..3.288 rows=51 loops=1) + Buffers: shared hit=10095 + -> Index Scan using messages_chat_created_idx on messages (cost=0.29..2170.70 rows=15000 width=78) (actual time=0.029..2.991 rows=10051 loops=1) + Index Cond: (chat_id = '9a29690f-123d-4123-9ca9-41776e552bc7'::uuid) + Buffers: shared hit=10095 +Planning Time: 0.166 ms +Execution Time: 3.325 ms + +## Без индекса (DROP INDEX в транзакции, затем ROLLBACK) + +### 1. Первая страница +SELECT id, chat_id, sender_id, text, created_at +FROM messages +WHERE chat_id = %(chat)s +ORDER BY created_at, id +LIMIT 51 + +Limit (cost=1146.93..1147.06 rows=51 width=78) (actual time=2.658..2.665 rows=51 loops=1) + Buffers: shared hit=340 + -> Sort (cost=1146.93..1184.43 rows=15000 width=78) (actual time=2.656..2.659 rows=51 loops=1) + Sort Key: created_at, id + Sort Method: top-N heapsort Memory: 36kB + Buffers: shared hit=340 + -> Seq Scan on messages (cost=0.00..646.50 rows=15000 width=78) (actual time=0.013..1.449 rows=15000 loops=1) + Filter: (chat_id = '9a29690f-123d-4123-9ca9-41776e552bc7'::uuid) + Rows Removed by Filter: 10000 + Buffers: shared hit=334 +Planning: + Buffers: shared hit=4 +Planning Time: 0.165 ms +Execution Time: 2.705 ms + +### 2. Глубокая страница, keyset (как в приложении) +SELECT id, chat_id, sender_id, text, created_at +FROM messages +WHERE chat_id = %(chat)s AND (created_at, id) > (%(t)s, %(i)s) +ORDER BY created_at, id +LIMIT 51 + +Limit (cost=937.84..937.97 rows=51 width=78) (actual time=1.914..1.922 rows=51 loops=1) + Buffers: shared hit=334 + -> Sort (cost=937.84..950.31 rows=4986 width=78) (actual time=1.913..1.917 rows=51 loops=1) + Sort Key: created_at, id + Sort Method: top-N heapsort Memory: 36kB + Buffers: shared hit=334 + -> Seq Scan on messages (cost=0.00..771.50 rows=4986 width=78) (actual time=0.009..1.542 rows=5000 loops=1) + Filter: ((chat_id = '9a29690f-123d-4123-9ca9-41776e552bc7'::uuid) AND (ROW(created_at, id) > ROW('2026-01-21 01:57:43.327018+00'::timestamp with time zone, '42bea608-77e6-48e1-b1ab-68d0c66a93a1'::uuid))) + Rows Removed by Filter: 20000 + Buffers: shared hit=334 +Planning Time: 0.146 ms +Execution Time: 1.952 ms diff --git a/evidence/persistence.txt b/evidence/persistence.txt new file mode 100644 index 00000000..3a34ff8e --- /dev/null +++ b/evidence/persistence.txt @@ -0,0 +1,20 @@ +# 2026-10-22T23:02:27Z commit 1737703 (+ uncommitted lab2 changes) +## before +api 2026-10-22T23:01:06.75626996Z restarts=0 +postgres 2026-10-22T23:02:12.807168479Z restarts=0 +redis 2026-10-22T23:01:53.373703389Z restarts=0 +## python tests/resilience.py --mode persistence --action-script scripts/restart.cmd (Windows-аналог restart.sh) +Executing explicit persistence hook; hook output suppressed to avoid leaking secrets. +PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. +## after +api 2026-10-22T23:02:38.431368388Z restarts=0 +postgres 2026-10-22T23:02:32.818584222Z restarts=0 +redis 2026-10-22T23:02:32.630052697Z restarts=0 +## bash scripts/restart.sh +exit=0 +api 2026-10-22T23:02:51.099774046Z restarts=0 +postgres 2026-10-22T23:02:45.493532708Z restarts=0 +redis 2026-10-22T23:02:45.552242386Z restarts=0 +## smoke after restart.sh +PASS: lab2 public API scenario; infrastructure and grading evidence remain separate. +## volume (не пересоздавался во время рестартов): kazakov_mtusi2026lab2_pgdata created 2026-10-22T22:35:31Z diff --git a/evidence/smoke.txt b/evidence/smoke.txt new file mode 100644 index 00000000..ef33e57f --- /dev/null +++ b/evidence/smoke.txt @@ -0,0 +1,5 @@ +# 2026-10-22T23:05:33Z +$ python scripts/check_contract.py +PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. +$ python tests/smoke.py --base-url http://localhost:8080 +PASS: lab2 public API scenario; infrastructure and grading evidence remain separate. diff --git a/evidence/test_auth.txt b/evidence/test_auth.txt new file mode 100644 index 00000000..4a3e9010 --- /dev/null +++ b/evidence/test_auth.txt @@ -0,0 +1,6 @@ +ok: wrong password / unknown user -> identical 401 +ok: Basic / X-User-Id / unknown token on business endpoint -> 401 +ok: session cached in redis +ok: logout revokes token even though it was cached +ok: redis FLUSHALL -> valid session still works, revoked stays revoked +PASS: test_auth diff --git a/evidence/test_expiry.txt b/evidence/test_expiry.txt new file mode 100644 index 00000000..3f993531 --- /dev/null +++ b/evidence/test_expiry.txt @@ -0,0 +1,2 @@ +ok: TTL=2s, after 3.5s the same token -> 401 (cache does not extend the session) +PASS: test_expiry diff --git a/evidence/test_outage.txt b/evidence/test_outage.txt new file mode 100644 index 00000000..eff36968 --- /dev/null +++ b/evidence/test_outage.txt @@ -0,0 +1,5 @@ +ok: redis stopped -> auth/read/write via PostgreSQL; first request 4.00s (until redis is marked down), next 0.026s; ready=200 +ok: redis started again -> cache used again +ok: postgres stopped -> write 503 in 5.02s, anonymous 401, unknown token 503, ready 503 +ok: postgres started again -> same token works, history intact +PASS: test_outage diff --git a/evidence/test_race.txt b/evidence/test_race.txt new file mode 100644 index 00000000..a32151c2 --- /dev/null +++ b/evidence/test_race.txt @@ -0,0 +1,3 @@ +registration race: 20 parallel requests -> 201 x1, 409 x19, other 0 +rollback: chat with unknown member -> 400, chat list unchanged, 0 orphan chats in DB +PASS: test_race diff --git a/evidence/track2-backup-restore.txt b/evidence/track2-backup-restore.txt new file mode 100644 index 00000000..0a8ef6c1 --- /dev/null +++ b/evidence/track2-backup-restore.txt @@ -0,0 +1,42 @@ +# Трек 2. Backup -> восстановление в новое хранилище -> сверка +# 2026-11-07T00:30:31Z; источник: база track2_lab в контейнере compose 'postgres'; цель: новый контейнер track2-restore (postgres:17.6-alpine) с новым пустым volume track2_restore_pgdata + +## Время и размер +pg_dump -Fc: 2.89 с, файл 9.0 MB (backups\track2_lab.dump) +старт нового контейнера PostgreSQL на пустом volume до готовности по TCP: 4.66 с +pg_restore (данные + PK/FK/индексы): 3.47 с +итого RTO (старт хранилища + restore, без доставки файла): 8.13 с + +## Сверка источник (на момент backup) vs восстановленная база +проверка | источник | восстановлено | совпало +users | 200 | 200 | да +chats | 1055 | 1055 | да +chat_members | 2110 | 2110 | да +messages | 160000 | 160000 | да +md5 всех сообщений (id, chat, sender, md5(text), created_at) | 7463388f43b1592b84e06f2a0bcbcda9 | 7463388f43b1592b84e06f2a0bcbcda9 | да +md5 распределения сообщений по чатам | dc93cd012a6771aaf4ac4a5f524da69a | dc93cd012a6771aaf4ac4a5f524da69a | да +индексы messages | messages_chat_created_idx, messages_pkey | messages_chat_created_idx, messages_pkey | да + +## Выбранные сообщения (7 шт.: 5 случайных + 2 последних в огромном чате) +08b00b62-8af3-4496-a8ff-405130f5fbbf | len(text)=1045 | created_at=2026-03-07T23:17:06.343914+00:00 | совпало +a67a59af-67a8-4c46-afda-89369e41c781 | len(text)=259 | created_at=2026-01-02T17:03:17.855575+00:00 | совпало +b6012a76-46b3-4bc6-8066-8cb6418cdb65 | len(text)=125 | created_at=2026-02-11T11:28:48.676199+00:00 | совпало +fbda3d64-77d6-4c0d-952e-7aaf4b281c5b | len(text)=131 | created_at=2026-03-15T23:32:07.340431+00:00 | совпало +702e2c4b-ed95-4d35-9ed1-47326e974e73 | len(text)=333 | created_at=2026-03-27T09:50:29.827956+00:00 | совпало +db327a11-099b-46e9-b31c-0c3b013557c6 | len(text)=12 | created_at=2026-04-01T00:00:26.715942+00:00 | совпало +3d70fe86-22df-4771-8df0-eef5532b6573 | len(text)=271 | created_at=2026-03-31T23:58:29.080342+00:00 | совпало + +## Граница потери данных (RPO) +после pg_dump в источник записано 1 сообщение (f45bd95e-8b52-4ba8-9588-2f02ecf9b142); сообщений в источнике стало 160001 +в восстановленной базе это сообщение: отсутствует — всё, что подтверждено после снимка, теряется при восстановлении из этого дампа + +## План истории в восстановленной базе (индекс восстановлен и используется) +Limit (cost=0.42..143.66 rows=51 width=552) (actual time=0.065..0.114 rows=51 loops=1) + Buffers: shared hit=14 read=4 + -> Index Scan using messages_chat_created_idx on messages (cost=0.42..17049.08 rows=6070 width=552) (actual time=0.064..0.108 rows=51 loops=1) + Index Cond: ((chat_id = 'd46b42f4-d27b-4257-86fb-407fc64745d5'::uuid) AND (ROW(created_at, id) > ROW('2026-03-23 00:00:03.21315+00'::timestamp with time zone, 'c3214402-3a2b-4c02-882a-141c5a6a15c1'::uuid))) + Buffers: shared hit=14 read=4 +Planning Time: 0.104 ms +Execution Time: 0.230 ms + +PASS: backup -> restore -> verification \ No newline at end of file diff --git a/evidence/track2-indexes.txt b/evidence/track2-indexes.txt new file mode 100644 index 00000000..99b17a5b --- /dev/null +++ b/evidence/track2-indexes.txt @@ -0,0 +1,116 @@ +# Трек 2. План запроса истории: сравнение индексов и стоимость записи +# 2026-11-07T00:29:41Z; PostgreSQL postgres:17.6-alpine; база track2_lab (отдельная от рабочей) +# медиана из 7 прогонов EXPLAIN (ANALYZE, BUFFERS); тёплый кэш (данные в shared_buffers) + +## Данные (генерация 14.9 с, setseed=0.42) +всего сообщений: 160000; таблица messages: heap 90.6 MB, всего с индексами 110.0 MB +вид чата | чатов | сообщений | средняя длина текста | макс. длина +huge | 1 | 60000 | 512 | 1999 +medium | 50 | 50000 | 512 | 1999 +large | 4 | 40000 | 511 | 1999 +small | 1000 | 10000 | 516 | 1999 + +## Варианты индексов +A: (chat_id, created_at, id) — текущий индекс приложения [CREATE INDEX v_idx ON messages (chat_id, created_at, id)] +B: (chat_id) — только фильтр по чату, сортировка отдельно [CREATE INDEX v_idx ON messages (chat_id)] +C: (created_at, id) — глобальный индекс по времени [CREATE INDEX v_idx ON messages (created_at, id)] +D: без дополнительного индекса (только PK) + +## Чтение страницы истории (LIMIT 51) +вариант | чат (сообщений) | страница | время, мс | буферов | план +A | huge (60000) | первая страница | 0.084 | 8 | Limit -> Index Scan (v_idx) +A | huge (60000) | keyset после 54000-го | 0.073 | 18 | Limit -> Index Scan (v_idx) +A | huge (60000) | OFFSET 54000 | 105.751 | 11691 | Limit -> Gather Merge -> Sort -> Seq Scan +A | medium (1000) | первая страница | 0.080 | 15 | Limit -> Index Scan (v_idx) +A | medium (1000) | keyset после 900-го | 0.069 | 9 | Limit -> Index Scan (v_idx) +A | small (10) | первая страница | 0.050 | 5 | Limit -> Index Scan (v_idx) +A | small (10) | keyset после 9-го | 0.069 | 4 | Limit -> Index Scan (v_idx) +B | huge (60000) | первая страница | 40.093 | 12509 | Limit -> Gather Merge -> Sort -> Seq Scan +B | huge (60000) | keyset после 54000-го | 20.725 | 4410 | Limit -> Sort -> Bitmap Heap Scan -> Bitmap Index Scan (v_idx) +B | huge (60000) | OFFSET 54000 | 116.635 | 12509 | Limit -> Gather Merge -> Sort -> Seq Scan +B | medium (1000) | первая страница | 0.875 | 110 | Limit -> Sort -> Index Scan (v_idx) +B | medium (1000) | keyset после 900-го | 0.769 | 110 | Limit -> Sort -> Index Scan (v_idx) +B | small (10) | первая страница | 0.114 | 4 | Limit -> Sort -> Index Scan (v_idx) +B | small (10) | keyset после 9-го | 0.114 | 4 | Limit -> Sort -> Index Scan (v_idx) +C | huge (60000) | первая страница | 0.069 | 51 | Limit -> Index Scan (v_idx) +C | huge (60000) | keyset после 54000-го | 0.574 | 1060 | Limit -> Index Scan (v_idx) +C | huge (60000) | OFFSET 54000 | 100.502 | 13389 | Limit -> Gather Merge -> Sort -> Seq Scan +C | medium (1000) | первая страница | 3.012 | 5750 | Limit -> Index Scan (v_idx) +C | medium (1000) | keyset после 900-го | 7.497 | 2274 | Limit -> Sort -> Bitmap Heap Scan -> Bitmap Index Scan (v_idx) +C | small (10) | первая страница | 24.930 | 13389 | Limit -> Gather Merge -> Sort -> Seq Scan +C | small (10) | keyset после 9-го | 6.375 | 2276 | Limit -> Sort -> Bitmap Heap Scan -> Bitmap Index Scan (v_idx) +D | huge (60000) | первая страница | 29.528 | 14269 | Limit -> Gather Merge -> Sort -> Seq Scan +D | huge (60000) | keyset после 54000-го | 25.963 | 14211 | Limit -> Gather Merge -> Sort -> Seq Scan +D | huge (60000) | OFFSET 54000 | 97.252 | 14269 | Limit -> Gather Merge -> Sort -> Seq Scan +D | medium (1000) | первая страница | 25.453 | 14269 | Limit -> Gather Merge -> Sort -> Seq Scan +D | medium (1000) | keyset после 900-го | 26.138 | 14211 | Limit -> Gather Merge -> Sort -> Seq Scan +D | small (10) | первая страница | 24.555 | 14269 | Limit -> Gather Merge -> Sort -> Seq Scan +D | small (10) | keyset после 9-го | 28.573 | 14181 | Limit -> Sort -> Gather -> Seq Scan + +## Стоимость записи (медиана из 3; каждая вставка в транзакции с ROLLBACK) +bulk = один INSERT ... SELECT на 20000 строк по всем чатам; single = 2000 отдельных INSERT (как API) +вариант | размер индекса | построение, мс | bulk, мс | bulk, мкс/строка | bulk WAL, Б/строка | single, мс | single, мкс/строка | single WAL, Б/строка +A | 9.0 MB | 148 | 1055 | 52.8 | 363 | 294 | 146.8 | 364 +B | 1.1 MB | 99 | 1209 | 60.4 | 308 | 301 | 150.6 | 340 +C | 6.2 MB | 115 | 1089 | 54.4 | 334 | 282 | 141.0 | 367 +D | — | 0 | 1098 | 54.9 | 227 | 277 | 138.3 | 257 + +## Полные планы: огромный чат, глубокая keyset-страница +### A: (chat_id, created_at, id) — текущий индекс приложения +Limit (cost=0.42..144.80 rows=51 width=556) (actual time=0.033..0.059 rows=51 loops=1) + Buffers: shared hit=18 + -> Index Scan using v_idx on messages (cost=0.42..16791.30 rows=5931 width=556) (actual time=0.032..0.053 rows=51 loops=1) + Index Cond: ((chat_id = 'd46b42f4-d27b-4257-86fb-407fc64745d5'::uuid) AND (ROW(created_at, id) > ROW('2026-03-23 00:00:03.21315+00'::timestamp with time zone, 'c3214402-3a2b-4c02-882a-141c5a6a15c1'::uuid))) + Buffers: shared hit=18 +Planning Time: 0.119 ms +Execution Time: 0.115 ms + +### B: (chat_id) — только фильтр по чату, сортировка отдельно +Limit (cost=14341.83..14341.96 rows=51 width=555) (actual time=15.370..15.381 rows=51 loops=1) + Buffers: shared hit=4410 + -> Sort (cost=14341.83..14357.18 rows=6141 width=555) (actual time=15.369..15.375 rows=51 loops=1) + Sort Key: created_at, id + Sort Method: top-N heapsort Memory: 66kB + Buffers: shared hit=4410 + -> Bitmap Heap Scan on messages (cost=670.07..14136.96 rows=6141 width=555) (actual time=4.268..14.464 rows=6000 loops=1) + Recheck Cond: (chat_id = 'd46b42f4-d27b-4257-86fb-407fc64745d5'::uuid) + Filter: (ROW(created_at, id) > ROW('2026-03-23 00:00:03.21315+00'::timestamp with time zone, 'c3214402-3a2b-4c02-882a-141c5a6a15c1'::uuid)) + Rows Removed by Filter: 54000 + Heap Blocks: exact=4357 + Buffers: shared hit=4410 + -> Bitmap Index Scan on v_idx (cost=0.00..668.53 rows=59765 width=0) (actual time=2.748..2.749 rows=60000 loops=1) + Index Cond: (chat_id = 'd46b42f4-d27b-4257-86fb-407fc64745d5'::uuid) + Buffers: shared hit=53 +Planning Time: 0.096 ms +Execution Time: 15.536 ms + +### C: (created_at, id) — глобальный индекс по времени +Limit (cost=0.42..338.22 rows=51 width=553) (actual time=0.370..0.397 rows=51 loops=1) + Buffers: shared hit=1060 + -> Index Scan using v_idx on messages (cost=0.42..39880.63 rows=6021 width=553) (actual time=0.369..0.393 rows=51 loops=1) + Index Cond: (ROW(created_at, id) > ROW('2026-03-23 00:00:03.21315+00'::timestamp with time zone, 'c3214402-3a2b-4c02-882a-141c5a6a15c1'::uuid)) + Filter: (chat_id = 'd46b42f4-d27b-4257-86fb-407fc64745d5'::uuid) + Rows Removed by Filter: 1029 + Buffers: shared hit=1060 +Planning Time: 0.057 ms +Execution Time: 0.420 ms + +### D: без дополнительного индекса (только PK) +Limit (cost=16431.40..16437.35 rows=51 width=558) (actual time=19.821..25.251 rows=51 loops=1) + Buffers: shared hit=14211 + -> Gather Merge (cost=16431.40..17016.87 rows=5018 width=558) (actual time=19.820..25.244 rows=51 loops=1) + Workers Planned: 2 + Workers Launched: 2 + Buffers: shared hit=14211 + -> Sort (cost=15431.37..15437.64 rows=2509 width=558) (actual time=15.548..15.552 rows=37 loops=3) + Sort Key: created_at, id + Sort Method: top-N heapsort Memory: 67kB + Buffers: shared hit=14211 + Worker 0: Sort Method: top-N heapsort Memory: 73kB + Worker 1: Sort Method: top-N heapsort Memory: 59kB + -> Parallel Seq Scan on messages (cost=0.00..15347.67 rows=2509 width=558) (actual time=1.661..15.040 rows=2000 loops=3) + Filter: ((chat_id = 'd46b42f4-d27b-4257-86fb-407fc64745d5'::uuid) AND (ROW(created_at, id) > ROW('2026-03-23 00:00:03.21315+00'::timestamp with time zone, 'c3214402-3a2b-4c02-882a-141c5a6a15c1'::uuid))) + Rows Removed by Filter: 51333 + Buffers: shared hit=14181 +Planning Time: 0.094 ms +Execution Time: 25.351 ms diff --git a/migrations/001_init.sql b/migrations/001_init.sql new file mode 100644 index 00000000..c2507900 --- /dev/null +++ b/migrations/001_init.sql @@ -0,0 +1,39 @@ +CREATE TABLE users ( + id UUID PRIMARY KEY, + username TEXT NOT NULL UNIQUE CHECK (username ~ '^[a-z0-9_]{3,32}$'), + display_name TEXT NOT NULL CHECK (char_length(display_name) BETWEEN 1 AND 100), + password_hash TEXT NOT NULL, + created_at TIMESTAMPTZ NOT NULL DEFAULT now() +); + +CREATE TABLE chats ( + id UUID PRIMARY KEY, + title TEXT NOT NULL CHECK (char_length(title) BETWEEN 1 AND 100), + created_at TIMESTAMPTZ NOT NULL DEFAULT now() +); + +CREATE TABLE chat_members ( + chat_id UUID NOT NULL REFERENCES chats(id), + user_id UUID NOT NULL REFERENCES users(id), + PRIMARY KEY (chat_id, user_id) +); + +CREATE TABLE messages ( + id UUID PRIMARY KEY, + chat_id UUID NOT NULL REFERENCES chats(id), + sender_id UUID NOT NULL REFERENCES users(id), + text TEXT NOT NULL CHECK (char_length(text) BETWEEN 1 AND 4000), + created_at TIMESTAMPTZ NOT NULL DEFAULT now() +); + +CREATE TABLE sessions ( + token_hash TEXT PRIMARY KEY, + user_id UUID NOT NULL REFERENCES users(id), + created_at TIMESTAMPTZ NOT NULL DEFAULT now(), + expires_at TIMESTAMPTZ NOT NULL, + revoked_at TIMESTAMPTZ +); + +CREATE INDEX messages_chat_created_idx ON messages (chat_id, created_at, id); +CREATE INDEX chat_members_user_idx ON chat_members (user_id); +CREATE INDEX sessions_user_idx ON sessions (user_id); \ No newline at end of file diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..4dc5a2b0 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,8 @@ +fastapi==0.161.1 +starlette==1.9.0 +pydantic==2.14.1 +uvicorn[standard]==0.54.0 +psycopg[binary]==3.3.6 +psycopg-pool==3.3.3 +argon2-cffi==25.1.0 +redis==8.1.0 diff --git a/schemas.py b/schemas.py new file mode 100644 index 00000000..138934e7 --- /dev/null +++ b/schemas.py @@ -0,0 +1,77 @@ +from pydantic import BaseModel, ConfigDict, Field, field_validator + + +def not_blank(value: str) -> str: + if not value.strip(): + raise ValueError("must not be blank") + return value + + +class RequestModel(BaseModel): + # Лишние поля и неверные типы в JSON -> 400 + model_config = ConfigDict(extra="forbid", strict=True) + + +# ---------- Запросы ---------- + +class CreateUser(RequestModel): + username: str = Field(pattern=r"^[a-z0-9_]{3,32}$") + display_name: str = Field(min_length=1, max_length=100) + password: str = Field(min_length=12, max_length=128) + + _display_name_not_blank = field_validator("display_name")(not_blank) + _password_not_blank = field_validator("password")(not_blank) + + +class CreateChat(RequestModel): + title: str = Field(min_length=1, max_length=100) + member_ids: list[str] = Field(min_length=1, max_length=100) + + _title_not_blank = field_validator("title")(not_blank) + + +class CreateMessage(RequestModel): + text: str = Field(min_length=1, max_length=4000) + + _text_not_blank = field_validator("text")(not_blank) + + +# ---------- Ответы ---------- + +class User(BaseModel): + id: str + username: str + display_name: str + created_at: str + + +class Session(BaseModel): + token: str + token_type: str = "Bearer" + expires_at: str + user: User + + +class Chat(BaseModel): + id: str + title: str + member_ids: list[str] + created_at: str + + +class ChatPage(BaseModel): + items: list[Chat] + next_cursor: str | None + + +class Message(BaseModel): + id: str + chat_id: str + sender_id: str + text: str + created_at: str + + +class MessagePage(BaseModel): + items: list[Message] + next_cursor: str | None diff --git a/scripts/restart.cmd b/scripts/restart.cmd new file mode 100644 index 00000000..2ce6e843 --- /dev/null +++ b/scripts/restart.cmd @@ -0,0 +1,7 @@ +@echo off +rem Windows-вариант scripts/restart.sh (тот же порядок действий, volumes сохраняются) +cd /d "%~dp0.." +docker compose --env-file .env stop api || exit /b 1 +docker compose --env-file .env restart postgres redis || exit /b 1 +docker compose --env-file .env start api || exit /b 1 +exit /b 0 diff --git a/scripts/restart.sh b/scripts/restart.sh new file mode 100755 index 00000000..b36b66fc --- /dev/null +++ b/scripts/restart.sh @@ -0,0 +1,8 @@ +#!/bin/sh +# Перезапуск API и ВСЕХ используемых хранилищ (PostgreSQL, Redis) с сохранением volumes. +# Никаких down -v / flush / повторного seed. +set -eu +cd "$(dirname "$0")/.." +docker compose --env-file .env stop api +docker compose --env-file .env restart postgres redis +docker compose --env-file .env start api diff --git a/student-tests/common.py b/student-tests/common.py new file mode 100644 index 00000000..a8b3cc31 --- /dev/null +++ b/student-tests/common.py @@ -0,0 +1,92 @@ +"""Общие помощники для собственных тестов (только стандартная библиотека).""" +import base64 +import json +import os +import subprocess +import sys +import time +import urllib.error +import urllib.request +import uuid +from pathlib import Path + +ROOT = Path(__file__).resolve().parent.parent +BASE = os.environ.get("BASE_URL", "http://localhost:8080").rstrip("/") +PASSWORD = "synthetic-pass-123" + + +class Failure(Exception): + pass + + +def check(cond, msg): + if not cond: + raise Failure(msg) + + +def call(method, path, body=None, headers=None, timeout=15): + h = dict(headers or {}) + data = None + if body is not None: + data = json.dumps(body).encode() + h["Content-Type"] = "application/json" + req = urllib.request.Request(BASE + path, data=data, method=method, headers=h) + started = time.monotonic() + try: + with urllib.request.urlopen(req, timeout=timeout) as r: + status, raw, rh = r.status, r.read(), r.headers + except urllib.error.HTTPError as e: + status, raw, rh = e.code, e.read(), e.headers + elapsed = time.monotonic() - started + payload = json.loads(raw) if raw else None + return status, payload, rh, elapsed + + +def basic(username, password): + return {"Authorization": "Basic " + base64.b64encode(f"{username}:{password}".encode()).decode()} + + +def bearer(token): + return {"Authorization": "Bearer " + token} + + +def new_user(prefix="t"): + name = prefix + uuid.uuid4().hex[:12] + st, body, _, _ = call("POST", "/api/v1/users", {"username": name, "display_name": "Synthetic", "password": PASSWORD}) + check(st == 201, f"register expected 201, got {st}") + return {"username": name, "id": body["id"]} + + +def login(user): + st, body, _, _ = call("POST", "/api/v1/auth/sessions", headers=basic(user["username"], PASSWORD)) + check(st == 201, f"login expected 201, got {st}") + return body + + +def compose(*args, env=None, check_rc=True): + cmd = ["docker", "compose", "--env-file", str(ROOT / ".env"), *args] + full_env = dict(os.environ, **(env or {})) + r = subprocess.run(cmd, cwd=ROOT, env=full_env, capture_output=True, text=True, encoding="utf-8", errors="replace") + if check_rc and r.returncode != 0: + raise Failure("docker compose " + " ".join(args) + " failed: " + r.stderr[-300:]) + return r.stdout + + +def wait_ready(timeout=90): + deadline = time.monotonic() + timeout + while time.monotonic() < deadline: + try: + if call("GET", "/health/ready", timeout=3)[0] == 200: + return + except Exception: + pass + time.sleep(0.5) + raise Failure("API did not become ready") + + +def run(main): + try: + main() + except Failure as e: + print("FAIL:", e) + sys.exit(1) diff --git a/student-tests/explain_history.py b/student-tests/explain_history.py new file mode 100644 index 00000000..01c1c031 --- /dev/null +++ b/student-tests/explain_history.py @@ -0,0 +1,124 @@ +"""EXPLAIN (ANALYZE, BUFFERS) запроса истории на >= 10 000 сообщений. + +Работает в ОТДЕЛЬНОЙ базе `explain_lab` того же PostgreSQL (основная база не трогается). +Сравнивает запрос приложения с индексом (chat_id, created_at, id) и без него. +Запуск (стек поднят, порт 5432 проброшен на 127.0.0.1): + python student-tests/explain_history.py +Результат: evidence/explain-history.txt +""" +from pathlib import Path + +import psycopg + +ROOT = Path(__file__).resolve().parent.parent +DB = "explain_lab" + + +def env(): + values = {} + for line in (ROOT / ".env").read_text(encoding="utf-8").splitlines(): + if "=" in line and not line.lstrip().startswith("#"): + k, v = line.split("=", 1) + values[k.strip()] = v.strip() + return values + + +E = env() +ADMIN_DSN = f"postgresql://{E['POSTGRES_USER']}:{E['POSTGRES_PASSWORD']}@127.0.0.1:5432/{E['POSTGRES_DB']}" +LAB_DSN = ADMIN_DSN.rsplit("/", 1)[0] + "/" + DB + +# Запрос приложения (list_messages): keyset-курсор, LIMIT 50+1 +KEYSET_SQL = """SELECT id, chat_id, sender_id, text, created_at +FROM messages +WHERE chat_id = %(chat)s AND (created_at, id) > (%(t)s, %(i)s) +ORDER BY created_at, id +LIMIT 51""" +FIRST_SQL = """SELECT id, chat_id, sender_id, text, created_at +FROM messages +WHERE chat_id = %(chat)s +ORDER BY created_at, id +LIMIT 51""" +# Для сравнения: OFFSET-пагинация (в приложении НЕ используется) +OFFSET_SQL = """SELECT id, chat_id, sender_id, text, created_at +FROM messages +WHERE chat_id = %(chat)s +ORDER BY created_at, id +OFFSET 10000 LIMIT 51""" + + +def explain(conn, sql, params): + rows = conn.execute("EXPLAIN (ANALYZE, BUFFERS) " + sql, params).fetchall() + return "\n".join(r[0] for r in rows) + + +def main(): + with psycopg.connect(ADMIN_DSN, autocommit=True) as c: + c.execute(f"DROP DATABASE IF EXISTS {DB} WITH (FORCE)") + c.execute(f"CREATE DATABASE {DB}") + + with psycopg.connect(LAB_DSN) as conn: + for f in sorted((ROOT / "migrations").glob("*.sql")): + conn.execute(f.read_text(encoding="utf-8")) + conn.execute("SELECT setseed(0.42)") + conn.execute(""" + INSERT INTO users (id, username, display_name, password_hash) + SELECT gen_random_uuid(), 'user_' || g, 'User ' || g, 'synthetic-not-a-hash' + FROM generate_series(1, 100) g""") + # 1 большой чат на 15 000 сообщений + 200 маленьких по 50 = 25 000 сообщений + conn.execute(""" + INSERT INTO chats (id, title) + SELECT gen_random_uuid(), CASE WHEN g = 1 THEN 'big' ELSE 'small' END + FROM generate_series(1, 201) g""") + conn.execute(""" + INSERT INTO chat_members (chat_id, user_id) + SELECT c.id, (SELECT id FROM users ORDER BY id LIMIT 1) FROM chats c""") + conn.execute(""" + INSERT INTO messages (id, chat_id, sender_id, text, created_at) + SELECT gen_random_uuid(), c.id, m.user_id, 'synthetic message ' || g, + timestamptz '2026-01-01' + random() * interval '30 days' + FROM chats c + JOIN chat_members m ON m.chat_id = c.id + CROSS JOIN LATERAL generate_series(1, CASE WHEN c.title = 'big' THEN 15000 ELSE 50 END) g""") + conn.commit() + + with psycopg.connect(LAB_DSN, autocommit=True) as c: + c.execute("VACUUM ANALYZE") + + with psycopg.connect(LAB_DSN) as conn: + total = conn.execute("SELECT count(*) FROM messages").fetchone()[0] + big = conn.execute("SELECT id FROM chats WHERE title = 'big'").fetchone()[0] + big_count = conn.execute("SELECT count(*) FROM messages WHERE chat_id = %s", (big,)).fetchone()[0] + deep = conn.execute("""SELECT created_at, id FROM messages WHERE chat_id = %s + ORDER BY created_at, id OFFSET 9999 LIMIT 1""", (big,)).fetchone() + params = {"chat": big, "t": deep[0], "i": deep[1]} + + out = [f"# EXPLAIN (ANALYZE, BUFFERS) истории сообщений", + f"# всего сообщений: {total}; в исследуемом чате: {big_count}", + "# keyset-курсор указывает на 10 000-е сообщение чата (глубокая страница)\n"] + cases = [("1. Первая страница", FIRST_SQL), + ("2. Глубокая страница, keyset (как в приложении)", KEYSET_SQL), + ("3. Глубокая страница через OFFSET 10000 (для сравнения)", OFFSET_SQL)] + + out.append("## С индексом messages_chat_created_idx (chat_id, created_at, id)\n") + for title, sql in cases: + explain(conn, sql, params) # прогрев + out.append(f"### {title}\n{sql}\n\n{explain(conn, sql, params)}\n") + + # Без индекса: DROP INDEX внутри транзакции и ROLLBACK — индекс вернётся + out.append("## Без индекса (DROP INDEX в транзакции, затем ROLLBACK)\n") + conn.execute("DROP INDEX messages_chat_created_idx") + for title, sql in cases[:2]: + out.append(f"### {title}\n{sql}\n\n{explain(conn, sql, params)}\n") + conn.rollback() + + with psycopg.connect(ADMIN_DSN, autocommit=True) as c: + c.execute(f"DROP DATABASE IF EXISTS {DB} WITH (FORCE)") + + text = "\n".join(out) + (ROOT / "evidence").mkdir(exist_ok=True) + (ROOT / "evidence" / "explain-history.txt").write_text(text, encoding="utf-8") + print(text) + + +if __name__ == "__main__": + main() diff --git a/student-tests/test_auth.py b/student-tests/test_auth.py new file mode 100644 index 00000000..4d5d005f --- /dev/null +++ b/student-tests/test_auth.py @@ -0,0 +1,48 @@ +"""Неверный пароль, Basic/X-User-Id на бизнес-endpoint, logout, инвалидация кэша сессий.""" +from common import * + + +def main(): + alice = new_user("auth") + st, body, h, _ = call("POST", "/api/v1/auth/sessions", headers=basic(alice["username"], "wrong-password-123")) + check(st == 401 and body["error"]["code"] == "unauthorized", "wrong password must be 401") + check(h.get("WWW-Authenticate", "").startswith("Basic"), "wrong password must return Basic challenge") + st2, _, h2, _ = call("POST", "/api/v1/auth/sessions", headers=basic("no_such_user_xyz", "wrong-password-123")) + check(st2 == 401 and h2.get("WWW-Authenticate") == h.get("WWW-Authenticate"), "unknown user must look the same as wrong password") + print("ok: wrong password / unknown user -> identical 401") + + check(call("GET", "/api/v1/users/me", headers=basic(alice["username"], PASSWORD))[0] == 401, "Basic on business endpoint") + check(call("GET", "/api/v1/users/me", headers={"X-User-Id": alice["id"]})[0] == 401, "X-User-Id alone must not authenticate") + st, _, h, _ = call("GET", "/api/v1/users/me", headers=bearer("x" * 43)) + check(st == 401 and h.get("WWW-Authenticate") == 'Bearer realm="messenger"', "unknown token must be 401 Bearer") + print("ok: Basic / X-User-Id / unknown token on business endpoint -> 401") + + session = login(alice) + token = session["token"] + check(len(token) >= 43 and alice["id"] not in token and alice["username"] not in token, "token must be opaque random") + # первый запрос кладёт сессию в кэш, второй читает её из Redis + check(call("GET", "/api/v1/users/me", headers=bearer(token))[0] == 200, "token works") + keys = compose("exec", "-T", "redis", "redis-cli", "--scan", "--pattern", "session:*") + check(keys.strip() != "", "session must be cached in redis") + check(call("GET", "/api/v1/users/me", headers=bearer(token))[0] == 200, "token works from cache") + print("ok: session cached in redis") + + st, body, _, _ = call("DELETE", "/api/v1/auth/sessions/current", headers=bearer(token)) + check(st == 204 and body is None, "logout must be 204 without body") + check(call("GET", "/api/v1/users/me", headers=bearer(token))[0] == 401, "token after logout must be 401 (cache invalidated)") + check(call("DELETE", "/api/v1/auth/sessions/current", headers=bearer(token))[0] == 401, "second logout must be 401") + print("ok: logout revokes token even though it was cached") + + # Redis — только кэш: после FLUSHALL действующая сессия читается из PostgreSQL, + # а отозванная не "воскресает" + s2 = login(alice) + s3 = login(alice) + call("DELETE", "/api/v1/auth/sessions/current", headers=bearer(s3["token"])) + compose("exec", "-T", "redis", "redis-cli", "FLUSHALL") + check(call("GET", "/api/v1/users/me", headers=bearer(s2["token"]))[0] == 200, "valid session must survive redis flush") + check(call("GET", "/api/v1/users/me", headers=bearer(s3["token"]))[0] == 401, "revoked session must stay revoked after flush") + print("ok: redis FLUSHALL -> valid session still works, revoked stays revoked") + print("PASS: test_auth") + + +run(main) diff --git a/student-tests/test_expiry.py b/student-tests/test_expiry.py new file mode 100644 index 00000000..94d3d086 --- /dev/null +++ b/student-tests/test_expiry.py @@ -0,0 +1,26 @@ +"""Истечение сессии: API перезапускается с SESSION_TTL_SECONDS=2, затем возвращается обычный TTL.""" +import time +from common import * + +TTL = 2 + + +def main(): + compose("up", "-d", "api", env={"SESSION_TTL_SECONDS": str(TTL)}) + wait_ready() + try: + alice = new_user("exp") + session = login(alice) + token = session["token"] + check(call("GET", "/api/v1/users/me", headers=bearer(token))[0] == 200, "fresh token works (and is cached)") + time.sleep(TTL + 1.5) + st, _, h, _ = call("GET", "/api/v1/users/me", headers=bearer(token)) + check(st == 401 and h.get("WWW-Authenticate", "").startswith("Bearer"), f"expired token must be 401, got {st}") + print(f"ok: TTL={TTL}s, after {TTL + 1.5}s the same token -> 401 (cache does not extend the session)") + finally: + compose("up", "-d", "api") # обычный TTL из .env + wait_ready() + print("PASS: test_expiry") + + +run(main) diff --git a/student-tests/test_outage.py b/student-tests/test_outage.py new file mode 100644 index 00000000..fbd44f87 --- /dev/null +++ b/student-tests/test_outage.py @@ -0,0 +1,55 @@ +"""Отказы зависимостей: Redis (обход кэша) и PostgreSQL (ограниченная ошибка 503, без доверия анониму).""" +import time +from common import * + + +def main(): + alice = new_user("out") + token = login(alice)["token"] + chat = call("POST", "/api/v1/chats", {"title": "Отказы", "member_ids": [alice["id"]]}, bearer(token))[1] + path = f"/api/v1/chats/{chat['id']}/messages" + + # --- Redis недоступен: работаем напрямую с PostgreSQL --- + compose("stop", "redis") + try: + st, _, _, t = call("GET", "/api/v1/users/me", headers=bearer(token)) + check(st == 200, f"redis down: valid token must still work via PostgreSQL, got {st}") + check(call("POST", path, {"text": "без redis"}, bearer(token))[0] == 201, "redis down: write must work") + check(call("GET", "/api/v1/users/me", headers=bearer("y" * 43))[0] == 401, "redis down: unknown token must be 401") + new_token = login(alice)["token"] + check(call("DELETE", "/api/v1/auth/sessions/current", headers=bearer(new_token))[0] == 204, "redis down: logout works") + check(call("GET", "/api/v1/users/me", headers=bearer(new_token))[0] == 401, "redis down: revoked token must be 401") + check(call("GET", "/health/ready")[0] == 200, "redis is not critical for readiness") + st, _, _, t2 = call("GET", "/api/v1/users/me", headers=bearer(token)) + check(st == 200 and t2 < 1, f"redis down: cache must be bypassed without waiting, took {t2:.2f}s") + print(f"ok: redis stopped -> auth/read/write via PostgreSQL; first request {t:.2f}s " + f"(until redis is marked down), next {t2:.3f}s; ready=200") + finally: + compose("start", "redis") + time.sleep(6) # RETRY_AFTER: приложение снова начинает использовать Redis + check(call("GET", "/api/v1/users/me", headers=bearer(token))[0] == 200, "after redis start") + print("ok: redis started again -> cache used again") + + # --- PostgreSQL недоступен: ограниченная ошибка 503, аноним/неизвестный токен не проходят --- + compose("stop", "postgres") + try: + st, body, _, t = call("POST", path, {"text": "без БД"}, bearer(token)) + check(st == 503 and body["error"]["code"] == "unavailable", f"db down: write must be 503, got {st}") + check(t < 12, f"db down: error must be bounded in time, took {t:.1f}s") + st_anon = call("GET", path)[0] + check(st_anon == 401, f"db down: anonymous must be 401, got {st_anon}") + st_fake = call("GET", path, headers=bearer("z" * 43))[0] + check(st_fake in (401, 503), f"db down: unknown token must never be 200, got {st_fake}") + st_ready = call("GET", "/health/ready")[0] + check(st_ready == 503, f"db down: readiness must be 503, got {st_ready}") + print(f"ok: postgres stopped -> write 503 in {t:.2f}s, anonymous 401, unknown token {st_fake}, ready 503") + finally: + compose("start", "postgres") + wait_ready() + st, page, _, _ = call("GET", path + "?limit=100", headers=bearer(token)) + check(st == 200 and [m["text"] for m in page["items"]] == ["без redis"], "after recovery: history intact, failed write absent") + print("ok: postgres started again -> same token works, history intact") + print("PASS: test_outage") + + +run(main) diff --git a/student-tests/test_race.py b/student-tests/test_race.py new file mode 100644 index 00000000..0d1a65e7 --- /dev/null +++ b/student-tests/test_race.py @@ -0,0 +1,34 @@ +"""Гонка регистрации одинакового username и откат составной операции создания чата.""" +import uuid +from concurrent.futures import ThreadPoolExecutor +from common import * + +N = 20 + + +def main(): + name = "race" + uuid.uuid4().hex[:10] + body = {"username": name, "display_name": "Race", "password": PASSWORD} + with ThreadPoolExecutor(N) as ex: + statuses = list(ex.map(lambda _: call("POST", "/api/v1/users", body)[0], range(N))) + created = statuses.count(201) + conflicts = statuses.count(409) + print(f"registration race: {N} parallel requests -> 201 x{created}, 409 x{conflicts}, other {N - created - conflicts}") + check(created == 1 and conflicts == N - 1, "exactly one registration must win, others 409") + + alice = new_user("rb") + token = login(alice)["token"] + before = call("GET", "/api/v1/chats?limit=100", headers=bearer(token))[1]["items"] + # участник alice вставится первым, неизвестный — вторым: без транзакции чат остался бы + st, err, _, _ = call("POST", "/api/v1/chats", {"title": "Откат", "member_ids": [alice["id"], str(uuid.uuid4())]}, bearer(token)) + check(st == 400, f"unknown member must be 400, got {st}") + after = call("GET", "/api/v1/chats?limit=100", headers=bearer(token))[1]["items"] + check(before == after, "failed chat creation must leave no chat/membership") + orphans = compose("exec", "-T", "postgres", "sh", "-c", + 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -tAc "SELECT count(*) FROM chats c WHERE NOT EXISTS (SELECT 1 FROM chat_members m WHERE m.chat_id = c.id)"') + check(orphans.strip() == "0", "chats without members exist in DB") + print("rollback: chat with unknown member -> 400, chat list unchanged, 0 orphan chats in DB") + print("PASS: test_race") + + +run(main) diff --git a/student-tests/track2_research.py b/student-tests/track2_research.py new file mode 100644 index 00000000..e7bed8e4 --- /dev/null +++ b/student-tests/track2_research.py @@ -0,0 +1,516 @@ +"""Трек 2 (оценка 5): план запроса истории и восстановление из backup. + +Всё выполняется в ОТДЕЛЬНОЙ базе `track2_lab` того же PostgreSQL — рабочая база +приложения не трогается. Нужен поднятый стек (docker compose up -d) и порт 5432 +на 127.0.0.1. На хосте нужен psycopg: pip install "psycopg[binary]" + + python student-tests/track2_research.py indexes # данные + сравнение индексов + стоимость записи + python student-tests/track2_research.py backup # pg_dump -> новое хранилище -> pg_restore -> сверка + python student-tests/track2_research.py all # оба этапа подряд + +Результаты: evidence/track2-indexes.txt, evidence/track2-backup-restore.txt +Дамп: backups/track2_lab.dump (каталог backups/ в .gitignore). +""" +import json +import statistics +import subprocess +import sys +import time +import uuid +from datetime import datetime, timezone +from pathlib import Path + +import psycopg + +ROOT = Path(__file__).resolve().parent.parent +DB = "track2_lab" +SEED = 0.42 +READ_RUNS = 7 # повторов каждого EXPLAIN ANALYZE, берём медиану +WRITE_RUNS = 3 # повторов каждого замера записи, берём медиану +BULK_ROWS = 20_000 # пакетная вставка одним INSERT ... SELECT +SINGLE_ROWS = 2_000 # вставка по одной строке (как делает API) + +# Неравномерное распределение: один огромный чат, несколько крупных, много мелких +CHAT_PLAN = [ # (вид, сколько чатов, сообщений в каждом) + ("huge", 1, 60_000), + ("large", 4, 10_000), + ("medium", 50, 1_000), + ("small", 1_000, 10), +] + +# Варианты индексов на messages (PK по id есть всегда) +VARIANTS = [ + ("A", "(chat_id, created_at, id) — текущий индекс приложения", + "CREATE INDEX v_idx ON messages (chat_id, created_at, id)"), + ("B", "(chat_id) — только фильтр по чату, сортировка отдельно", + "CREATE INDEX v_idx ON messages (chat_id)"), + ("C", "(created_at, id) — глобальный индекс по времени", + "CREATE INDEX v_idx ON messages (created_at, id)"), + ("D", "без дополнительного индекса (только PK)", None), +] + +FIRST_SQL = """SELECT id, chat_id, sender_id, text, created_at +FROM messages +WHERE chat_id = %(chat)s +ORDER BY created_at, id +LIMIT 51""" + +KEYSET_SQL = """SELECT id, chat_id, sender_id, text, created_at +FROM messages +WHERE chat_id = %(chat)s AND (created_at, id) > (%(t)s, %(i)s) +ORDER BY created_at, id +LIMIT 51""" + +OFFSET_SQL = """SELECT id, chat_id, sender_id, text, created_at +FROM messages +WHERE chat_id = %(chat)s +ORDER BY created_at, id +OFFSET %(off)s LIMIT 51""" + + +# ---------- окружение ---------- + +def env(): + values = {} + for line in (ROOT / ".env").read_text(encoding="utf-8").splitlines(): + if "=" in line and not line.lstrip().startswith("#"): + k, v = line.split("=", 1) + values[k.strip()] = v.strip() + return values + + +E = env() +USER, PASSWORD = E["POSTGRES_USER"], E["POSTGRES_PASSWORD"] +ADMIN_DSN = f"postgresql://{USER}:{PASSWORD}@127.0.0.1:5432/{E['POSTGRES_DB']}" +LAB_DSN = f"postgresql://{USER}:{PASSWORD}@127.0.0.1:5432/{DB}" + +RESTORE_CONTAINER = "track2-restore" +RESTORE_VOLUME = "track2_restore_pgdata" +RESTORE_PORT = 55432 +RESTORE_DSN = f"postgresql://{USER}:{PASSWORD}@127.0.0.1:{RESTORE_PORT}/{DB}" +PG_IMAGE = "postgres:17.6-alpine" # тот же образ, что в compose.yaml + + +def run(cmd, stdin=None, check=True, capture=True): + r = subprocess.run(cmd, cwd=ROOT, input=stdin, capture_output=capture) + if check and r.returncode != 0: + err = (r.stderr or b"").decode("utf-8", "replace")[-500:] + raise SystemExit(f"FAIL: {' '.join(cmd[:4])} ... -> {err}") + return r + + +def compose_exec(*args, stdin=None): + return run(["docker", "compose", "--env-file", ".env", "exec", "-T", "postgres", *args], stdin=stdin) + + +def now(): + return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") + + +def human(n_bytes): + for unit in ("B", "KB", "MB", "GB"): + if n_bytes < 1024: + return f"{n_bytes:.1f} {unit}" + n_bytes /= 1024 + return f"{n_bytes:.1f} TB" + + +# ---------- данные ---------- + +def create_dataset(): + with psycopg.connect(ADMIN_DSN, autocommit=True) as c: + c.execute(f"DROP DATABASE IF EXISTS {DB} WITH (FORCE)") + c.execute(f"CREATE DATABASE {DB}") + + plan_values = ", ".join(f"('{k}', {cnt}, {n})" for k, cnt, n in CHAT_PLAN) + t0 = time.monotonic() + with psycopg.connect(LAB_DSN) as conn: + for f in sorted((ROOT / "migrations").glob("*.sql")): + conn.execute(f.read_text(encoding="utf-8")) + conn.execute("SELECT setseed(%s)", (SEED,)) + conn.execute(""" + INSERT INTO users (id, username, display_name, password_hash) + SELECT gen_random_uuid(), 'user_' || g, 'User ' || g, 'synthetic-not-a-hash' + FROM generate_series(1, 200) g""") + conn.execute(f""" + CREATE TEMP TABLE chat_plan AS + SELECT gen_random_uuid() AS id, v.kind, v.n, + row_number() OVER () AS rn + FROM (VALUES {plan_values}) v(kind, cnt, n) + CROSS JOIN LATERAL generate_series(1, v.cnt)""") + conn.execute(""" + INSERT INTO chats (id, title, created_at) + SELECT id, kind || '-' || rn, timestamptz '2026-01-01' FROM chat_plan""") + # по 2 участника на чат + conn.execute(""" + WITH u AS (SELECT array_agg(id ORDER BY username) AS ids FROM users) + INSERT INTO chat_members (chat_id, user_id) + SELECT p.id, u.ids[(p.rn % 200) + 1] FROM chat_plan p, u + UNION ALL + SELECT p.id, u.ids[((p.rn + 1) % 200) + 1] FROM chat_plan p, u""") + # Сообщения: длина текста неравномерная (большинство короткие, есть до 2000 символов), + # время — по порядку внутри чата с небольшим разбросом, как в живой переписке + conn.execute(""" + WITH u AS (SELECT array_agg(id ORDER BY username) AS ids FROM users) + INSERT INTO messages (id, chat_id, sender_id, text, created_at) + SELECT gen_random_uuid(), p.id, + CASE WHEN g % 2 = 0 THEN u.ids[(p.rn % 200) + 1] + ELSE u.ids[((p.rn + 1) % 200) + 1] END, + left(repeat(md5(g::text || p.rn::text), 63), + 10 + floor(power(random(), 3) * 1990)::int), + timestamptz '2026-01-01' + + (g * interval '90 days' / p.n) + + random() * interval '1 minute' + FROM chat_plan p, u + CROSS JOIN LATERAL generate_series(1, p.n) g""") + conn.commit() + with psycopg.connect(LAB_DSN, autocommit=True) as c: + c.execute("VACUUM ANALYZE") + return time.monotonic() - t0 + + +def dataset_stats(conn): + total = conn.execute("SELECT count(*) FROM messages").fetchone()[0] + per_kind = conn.execute(""" + SELECT split_part(c.title, '-', 1) AS kind, count(DISTINCT c.id), count(m.id), + round(avg(length(m.text))), max(length(m.text)) + FROM chats c JOIN messages m ON m.chat_id = c.id + GROUP BY 1 ORDER BY 3 DESC""").fetchall() + size = conn.execute("SELECT pg_total_relation_size('messages')").fetchone()[0] + heap = conn.execute("SELECT pg_relation_size('messages')").fetchone()[0] + return total, per_kind, size, heap + + +def pick_chat(conn, kind): + return conn.execute( + "SELECT id FROM chats WHERE title LIKE %s ORDER BY title LIMIT 1", (kind + "-%",) + ).fetchone()[0] + + +def deep_cursor(conn, chat, fraction=0.9): + n = conn.execute("SELECT count(*) FROM messages WHERE chat_id = %s", (chat,)).fetchone()[0] + off = max(0, int(n * fraction) - 1) + row = conn.execute( + "SELECT created_at, id FROM messages WHERE chat_id = %s ORDER BY created_at, id OFFSET %s LIMIT 1", + (chat, off), + ).fetchone() + return n, off, row + + +# ---------- EXPLAIN ---------- + +def plan_nodes(node, acc): + name = node["Node Type"] + if node.get("Index Name"): + name += f" ({node['Index Name']})" + acc.append(name) + for child in node.get("Plans", []): + plan_nodes(child, acc) + return acc + + +def measure_read(conn, sql, params): + times = [] + plan = None + for _ in range(READ_RUNS): + res = conn.execute("EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) " + sql, params).fetchone()[0] + plan = res[0] if isinstance(res, list) else json.loads(res)[0] + times.append(plan["Execution Time"]) + top = plan["Plan"] + buffers = top.get("Shared Hit Blocks", 0) + top.get("Shared Read Blocks", 0) + nodes = " -> ".join(plan_nodes(top, [])) + return statistics.median(times), buffers, nodes + + +def explain_text(conn, sql, params): + rows = conn.execute("EXPLAIN (ANALYZE, BUFFERS) " + sql, params).fetchall() + return "\n".join(r[0] for r in rows) + + +# ---------- запись ---------- + +def measure_write(conn, chat_ids, mode): + """Вставка в транзакции с ROLLBACK: данные не меняются, замеры повторяемы.""" + times, wal = [], [] + for _ in range(WRITE_RUNS): + conn.execute("BEGIN") + lsn0 = conn.execute("SELECT pg_current_wal_insert_lsn()").fetchone()[0] + t0 = time.perf_counter() + if mode == "bulk": + # строки разбрасываются по всем чатам (как реальный поток сообщений) + conn.execute(""" + WITH p AS (SELECT array_agg(chat_id ORDER BY chat_id, user_id) AS c, + array_agg(user_id ORDER BY chat_id, user_id) AS u, + count(*) AS n + FROM chat_members) + INSERT INTO messages (id, chat_id, sender_id, text, created_at) + SELECT gen_random_uuid(), p.c[(g * 7919) %% p.n + 1], p.u[(g * 7919) %% p.n + 1], + 'bulk write test ' || g, now() + g * interval '1 millisecond' + FROM p, generate_series(1, %s) g""", (BULK_ROWS,)) + rows = BULK_ROWS + else: + with conn.cursor() as cur: + cur.executemany( + "INSERT INTO messages (id, chat_id, sender_id, text) VALUES (%s, %s, %s, %s)", + [(uuid.uuid4(), chat_ids[i % len(chat_ids)][0], chat_ids[i % len(chat_ids)][1], + f"single write test {i}") for i in range(SINGLE_ROWS)], + ) + rows = SINGLE_ROWS + elapsed = time.perf_counter() - t0 + lsn1 = conn.execute("SELECT pg_current_wal_insert_lsn()").fetchone()[0] + wal_bytes = conn.execute("SELECT pg_wal_lsn_diff(%s, %s)", (lsn1, lsn0)).fetchone()[0] + conn.execute("ROLLBACK") + times.append(elapsed) + wal.append(float(wal_bytes)) + t = statistics.median(times) + return t * 1000, t / rows * 1e6, statistics.median(wal) / rows + + +# ---------- этап 1: индексы ---------- + +def stage_indexes(): + out = [f"# Трек 2. План запроса истории: сравнение индексов и стоимость записи", + f"# {now()}; PostgreSQL {PG_IMAGE}; база {DB} (отдельная от рабочей)", + f"# медиана из {READ_RUNS} прогонов EXPLAIN (ANALYZE, BUFFERS); тёплый кэш (данные в shared_buffers)", + ""] + print("seeding dataset ...", flush=True) + seed_sec = create_dataset() + + with psycopg.connect(LAB_DSN, autocommit=True) as conn: + total, per_kind, size, heap = dataset_stats(conn) + out.append(f"## Данные (генерация {seed_sec:.1f} с, setseed={SEED})") + out.append(f"всего сообщений: {total}; таблица messages: heap {human(heap)}, всего с индексами {human(size)}") + out.append("вид чата | чатов | сообщений | средняя длина текста | макс. длина") + for kind, chats, msgs, avg_len, max_len in per_kind: + out.append(f"{kind} | {chats} | {msgs} | {avg_len} | {max_len}") + out.append("") + + chats = {k: pick_chat(conn, k) for k in ("huge", "medium", "small")} + cases = [] + for kind, chat in chats.items(): + n, off, (t, i) = deep_cursor(conn, chat) + cases.append((kind, n, "первая страница", FIRST_SQL, {"chat": chat})) + cases.append((kind, n, f"keyset после {off + 1}-го", KEYSET_SQL, {"chat": chat, "t": t, "i": i})) + if kind == "huge": + cases.append((kind, n, f"OFFSET {off + 1}", OFFSET_SQL, {"chat": chat, "off": off + 1})) + member_pairs = conn.execute("SELECT chat_id, user_id FROM chat_members ORDER BY chat_id").fetchall() + + conn.execute("DROP INDEX messages_chat_created_idx") + + read_rows, write_rows, sample_plans = [], [], [] + for code, title, ddl in VARIANTS: + print(f"variant {code}: {title}", flush=True) + build_ms, idx_size = 0.0, 0 + if ddl: + t0 = time.perf_counter() + conn.execute(ddl) + build_ms = (time.perf_counter() - t0) * 1000 + idx_size = conn.execute("SELECT pg_relation_size('v_idx')").fetchone()[0] + conn.execute("ANALYZE messages") + + for kind, n, label, sql, params in cases: + ms, buf, nodes = measure_read(conn, sql, params) + read_rows.append((code, kind, n, label, ms, buf, nodes)) + if kind == "huge" and label.startswith("keyset"): + sample_plans.append((code, title, sql, explain_text(conn, sql, params))) + + bulk_ms, bulk_us, bulk_wal = measure_write(conn, member_pairs, "bulk") + one_ms, one_us, one_wal = measure_write(conn, member_pairs, "single") + write_rows.append((code, title, idx_size, build_ms, bulk_ms, bulk_us, bulk_wal, one_ms, one_us, one_wal)) + + if ddl: + conn.execute("DROP INDEX v_idx") + + # вернуть рабочий индекс приложения (нужен для этапа backup) + conn.execute("CREATE INDEX messages_chat_created_idx ON messages (chat_id, created_at, id)") + conn.execute("ANALYZE messages") + + out.append("## Варианты индексов") + for code, title, ddl in VARIANTS: + out.append(f"{code}: {title}" + (f" [{ddl}]" if ddl else "")) + out.append("") + + out.append("## Чтение страницы истории (LIMIT 51)") + out.append("вариант | чат (сообщений) | страница | время, мс | буферов | план") + for code, kind, n, label, ms, buf, nodes in read_rows: + out.append(f"{code} | {kind} ({n}) | {label} | {ms:.3f} | {buf} | {nodes}") + out.append("") + + out.append(f"## Стоимость записи (медиана из {WRITE_RUNS}; каждая вставка в транзакции с ROLLBACK)") + out.append(f"bulk = один INSERT ... SELECT на {BULK_ROWS} строк по всем чатам; " + f"single = {SINGLE_ROWS} отдельных INSERT (как API)") + out.append("вариант | размер индекса | построение, мс | bulk, мс | bulk, мкс/строка | bulk WAL, Б/строка" + " | single, мс | single, мкс/строка | single WAL, Б/строка") + for code, title, idx_size, build_ms, bulk_ms, bulk_us, bulk_wal, one_ms, one_us, one_wal in write_rows: + out.append(f"{code} | {human(idx_size) if idx_size else '—'} | {build_ms:.0f} | {bulk_ms:.0f} | " + f"{bulk_us:.1f} | {bulk_wal:.0f} | {one_ms:.0f} | {one_us:.1f} | {one_wal:.0f}") + out.append("") + + out.append("## Полные планы: огромный чат, глубокая keyset-страница") + for code, title, sql, text in sample_plans: + out.append(f"### {code}: {title}\n{text}\n") + + text = "\n".join(out) + (ROOT / "evidence").mkdir(exist_ok=True) + (ROOT / "evidence" / "track2-indexes.txt").write_text(text, encoding="utf-8") + print(text) + + +# ---------- этап 2: backup / restore ---------- + +CHECKS = { + "users": "SELECT count(*) FROM users", + "chats": "SELECT count(*) FROM chats", + "chat_members": "SELECT count(*) FROM chat_members", + "messages": "SELECT count(*) FROM messages", + "md5 всех сообщений (id, chat, sender, md5(text), created_at)": + "SELECT md5(string_agg(id::text || chat_id::text || sender_id::text || md5(text) || " + "extract(epoch FROM created_at)::text, ',' ORDER BY id)) FROM messages", + "md5 распределения сообщений по чатам": + "SELECT md5(string_agg(chat_id::text || ':' || n, ',' ORDER BY chat_id)) " + "FROM (SELECT chat_id, count(*) n FROM messages GROUP BY chat_id) s", + "индексы messages": + "SELECT string_agg(indexname, ', ' ORDER BY indexname) FROM pg_indexes WHERE tablename = 'messages'", +} + + +def snapshot(conn): + return {name: str(conn.execute(sql).fetchone()[0]) for name, sql in CHECKS.items()} + + +def sample_rows(conn, ids): + return { + str(r[0]): (str(r[1]), str(r[2]), r[3], r[4].isoformat()) + for r in conn.execute( + "SELECT id, chat_id, sender_id, text, created_at FROM messages WHERE id = ANY(%s)", (ids,) + ).fetchall() + } + + +def wait_restore_ready(timeout=120): + deadline = time.monotonic() + timeout + while time.monotonic() < deadline: + # -h 127.0.0.1: TCP. Временный сервер initdb слушает только unix-сокет, поэтому + # готовность по TCP означает, что инициализация контейнера завершена. + r = run(["docker", "exec", RESTORE_CONTAINER, "pg_isready", "-h", "127.0.0.1", "-U", USER, "-d", DB], + check=False) + if r.returncode == 0: + return + time.sleep(0.5) + raise SystemExit("FAIL: restore container did not become ready") + + +def cleanup_restore(): + run(["docker", "rm", "-f", RESTORE_CONTAINER], check=False) + run(["docker", "volume", "rm", "-f", RESTORE_VOLUME], check=False) + + +def stage_backup(): + out = [f"# Трек 2. Backup -> восстановление в новое хранилище -> сверка", + f"# {now()}; источник: база {DB} в контейнере compose 'postgres'; " + f"цель: новый контейнер {RESTORE_CONTAINER} ({PG_IMAGE}) с новым пустым volume {RESTORE_VOLUME}", + ""] + with psycopg.connect(LAB_DSN, autocommit=True) as src: + before = snapshot(src) + sample_ids = [r[0] for r in src.execute( + "SELECT id FROM messages ORDER BY md5(id::text) LIMIT 5").fetchall()] + huge = pick_chat(src, "huge") + sample_ids += [r[0] for r in src.execute( + "SELECT id FROM messages WHERE chat_id = %s ORDER BY created_at DESC, id DESC LIMIT 2", + (huge,)).fetchall()] + src_rows = sample_rows(src, sample_ids) + + # 1. Backup: pg_dump в custom-формате (сжатый, восстанавливается pg_restore) + backups = ROOT / "backups" + backups.mkdir(exist_ok=True) + dump_path = backups / f"{DB}.dump" + t0 = time.monotonic() + dump = compose_exec("pg_dump", "-U", USER, "-d", DB, "-Fc").stdout + dump_sec = time.monotonic() - t0 + dump_path.write_bytes(dump) + + # 2. Запись ПОСЛЕ backup — показывает границу потери данных (RPO) + late_id = uuid.uuid4() + with psycopg.connect(LAB_DSN, autocommit=True) as src: + member = src.execute("SELECT chat_id, user_id FROM chat_members WHERE chat_id = %s LIMIT 1", + (huge,)).fetchone() + src.execute("INSERT INTO messages (id, chat_id, sender_id, text) VALUES (%s, %s, %s, %s)", + (late_id, member[0], member[1], "written after backup")) + after_src_count = src.execute("SELECT count(*) FROM messages").fetchone()[0] + + # 3. Новое хранилище: отдельный контейнер и новый пустой volume + cleanup_restore() + t0 = time.monotonic() + run(["docker", "run", "-d", "--name", RESTORE_CONTAINER, + "-e", f"POSTGRES_USER={USER}", "-e", f"POSTGRES_PASSWORD={PASSWORD}", "-e", f"POSTGRES_DB={DB}", + "-v", f"{RESTORE_VOLUME}:/var/lib/postgresql/data", + "-p", f"127.0.0.1:{RESTORE_PORT}:5432", PG_IMAGE]) + wait_restore_ready() + start_sec = time.monotonic() - t0 + + # 4. Restore + t0 = time.monotonic() + run(["docker", "exec", "-i", RESTORE_CONTAINER, "pg_restore", "-U", USER, "-d", DB, + "--no-owner", "--exit-on-error"], stdin=dump) + restore_sec = time.monotonic() - t0 + + # 5. Сверка + with psycopg.connect(RESTORE_DSN, autocommit=True) as dst: + dst.execute("ANALYZE") + after = snapshot(dst) + dst_rows = sample_rows(dst, sample_ids) + late_in_restore = dst.execute("SELECT count(*) FROM messages WHERE id = %s", (late_id,)).fetchone()[0] + n, off, (t, i) = deep_cursor(dst, huge) + restored_plan = explain_text(dst, KEYSET_SQL, {"chat": huge, "t": t, "i": i}) + + ok = True + out.append("## Время и размер") + out.append(f"pg_dump -Fc: {dump_sec:.2f} с, файл {human(len(dump))} ({dump_path.relative_to(ROOT)})") + out.append(f"старт нового контейнера PostgreSQL на пустом volume до готовности по TCP: {start_sec:.2f} с") + out.append(f"pg_restore (данные + PK/FK/индексы): {restore_sec:.2f} с") + out.append(f"итого RTO (старт хранилища + restore, без доставки файла): {start_sec + restore_sec:.2f} с") + out.append("") + out.append("## Сверка источник (на момент backup) vs восстановленная база") + out.append("проверка | источник | восстановлено | совпало") + for name in CHECKS: + same = before[name] == after[name] + ok &= same + out.append(f"{name} | {before[name]} | {after[name]} | {'да' if same else 'НЕТ'}") + out.append("") + out.append(f"## Выбранные сообщения ({len(sample_ids)} шт.: 5 случайных + 2 последних в огромном чате)") + for mid in map(str, sample_ids): + same = src_rows.get(mid) == dst_rows.get(mid) + ok &= same + text = src_rows[mid][2] + out.append(f"{mid} | len(text)={len(text)} | created_at={src_rows[mid][3]} | {'совпало' if same else 'НЕ СОВПАЛО'}") + out.append("") + out.append("## Граница потери данных (RPO)") + out.append(f"после pg_dump в источник записано 1 сообщение ({late_id}); сообщений в источнике стало {after_src_count}") + out.append(f"в восстановленной базе это сообщение: {'есть' if late_in_restore else 'отсутствует'} " + "— всё, что подтверждено после снимка, теряется при восстановлении из этого дампа") + ok &= late_in_restore == 0 + out.append("") + out.append("## План истории в восстановленной базе (индекс восстановлен и используется)") + out.append(restored_plan) + out.append("") + out.append("PASS: backup -> restore -> verification" if ok else "FAIL: restored data differs") + + cleanup_restore() + with psycopg.connect(ADMIN_DSN, autocommit=True) as c: + c.execute(f"DROP DATABASE IF EXISTS {DB} WITH (FORCE)") + + text = "\n".join(out) + (ROOT / "evidence" / "track2-backup-restore.txt").write_text(text, encoding="utf-8") + print(text) + if not ok: + sys.exit(1) + + +if __name__ == "__main__": + stage = sys.argv[1] if len(sys.argv) > 1 else "all" + if stage not in ("indexes", "backup", "all"): + raise SystemExit(__doc__) + if stage in ("indexes", "all"): + stage_indexes() + if stage in ("backup", "all"): + stage_backup()