2 Commits
Author SHA1 Message Date
amin 3ed1c4e5b6 lab2
Skeleton contracts / contracts (pull_request) Canceled after 0s
2026-11-13 20:42:10 +03:00
amin 17377031cc схема бд и компоуз с постгресс 2026-10-23 01:32:02 +03:00
30 changed files with 2287 additions and 26 deletions
+15 -10
View File
@@ -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)
+1
View File
@@ -0,0 +1 @@
*.sh text eol=lf
+21
View File
@@ -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"]
+194 -15
View File
@@ -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:<sha256>` → `{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.
+490
View File
@@ -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)
+122
View File
@@ -0,0 +1,122 @@
"""Кэш сессий в Redis.
Источник истины для сессий — PostgreSQL (таблица sessions). Redis только ускоряет
проверку Bearer-токена, чтобы не ходить в БД на каждый запрос.
Политика:
- ключ session:<sha256(token)>; значение — 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)
-1
View File
@@ -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: {}
+51
View File
@@ -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:
+66
View File
@@ -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)
+94
View File
@@ -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
+20
View File
@@ -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
+5
View File
@@ -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.
+6
View File
@@ -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
+2
View File
@@ -0,0 +1,2 @@
ok: TTL=2s, after 3.5s the same token -> 401 (cache does not extend the session)
PASS: test_expiry
+5
View File
@@ -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
+3
View File
@@ -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
+42
View File
@@ -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
+116
View File
@@ -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
+39
View File
@@ -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);
+8
View File
@@ -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
+77
View File
@@ -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
+7
View File
@@ -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
+8
View File
@@ -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
+92
View File
@@ -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)
+124
View File
@@ -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()
+48
View File
@@ -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)
+26
View File
@@ -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)
+55
View File
@@ -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)
+34
View File
@@ -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)
+516
View File
@@ -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()